Add auto-linking of fully qualified property and method names (#201)

* Minor auto-linking tweaks.

- Do not auto-link a class or constructor name if followed by .<alphanumeric> (E.g. a fully-qualified property or method)
- Do not auto-link a property name in a property docstring if preceded or followed by <non-breaking space>.

* Add auto-linking of fully qualified property and method names.

- Requires matlab_auto_link = "all"

Author: rdzman

README.rst

@@ -82,7 +82,7 @@ Additional Configuration
 
 ``matlab_auto_link``
    Automatically convert the names of known entities (e.g. classes, functions,
-   properties, methods) to links Valid values are ``"basic"``
+   properties, methods) to links. Valid values are ``"basic"``
    and ``"all"``.
 
    * ``"basic"`` - Auto-links (1) known classes, functions, properties, or
@@ -94,6 +94,7 @@ Additional Configuration
 
    * ``"all"`` - Auto-links everything included with ``"basic"``, plus all known
      classes and functions everywhere else they appear in any docstring, any
+     fully qualified (including class name) property or method names, any
      names ending with "()" within class, property, or method docstrings that
      match a method of the corresponding class, and any property or method names
      in their own docstrings. Note that a non-breaking space before or after

sphinxcontrib/mat_documenters.py

@@ -285,12 +285,21 @@ def auto_link_all(self, docstrings):
             role = o.ref_role()
             if role in ["class", "func"]:
                 nn = n.replace("+", "")  # remove + from name
-                pat = (
-                    r"(?<!(`|\.|\+|<|@| ))\b"  # negative look-behind for ` . + < @ <non-breaking space>
-                    + nn.replace(".", r"\.")  # escape .
-                    + r"\b(?!(`| |\sProperties|\sMethods):)"  # negative look-ahead for ` or " Properties:" or " Methods:"
-                )
+                # negative look-behind for ` . + < @ <non-breaking space>
+                look_behind = r"(?<!(`|\.|\+|<|@| ))\b"
+                # negative look-ahead for ` or <non-breaking space> or
+                # " Properties:" or " Methods:" or .<alphanum>
+                look_ahead = r"\b(?!(`| |\sProperties:|\sMethods:|\.\w))"
+                look_ahead2 = r"\b(?!(`| |\sProperties:|\sMethods:))"
+                # entity_name is NOT followed by .<property_or_method>
+                pat = look_behind + nn.replace(".", r"\.") + look_ahead
                 p = re.compile(pat)
+                if role == "class":
+                    # entity_name IS followed by .<property_or_method>
+                    pat2 = (
+                        look_behind + nn.replace(".", r"\.") + r"\.(\w+)" + look_ahead2
+                    )
+                    p2 = re.compile(pat2)
                 no_link_state = 0  # normal mode (no literal block detected)
                 for i in range(len(docstrings)):
                     for j in range(len(docstrings[i])):
@@ -301,6 +310,24 @@ def auto_link_all(self, docstrings):
                             docstrings[i][j] = p.sub(
                                 f":{role}:`{nn}`", docstrings[i][j]
                             )
+                            if role == "class":
+                                if match := p2.search(docstrings[i][j]):
+                                    # if match.group(1) is a property
+                                    #   -> :attr:`{nn}.{match.group(1)}`
+                                    for nnn, ooo in o.properties.items():
+                                        if match.group(2) == nnn:
+                                            docstrings[i][j] = p2.sub(
+                                                f":attr:`{nn}.{nnn}`", docstrings[i][j]
+                                            )
+                                            break
+                                    # if match.group(1) is a method
+                                    #   -> :meth:`{nn}.{match.group(1)}`
+                                    for nnn, ooo in o.methods.items():
+                                        if match.group(2) == nnn:
+                                            docstrings[i][j] = p2.sub(
+                                                f":meth:`{nn}.{nnn}`", docstrings[i][j]
+                                            )
+                                            break
 
         return docstrings
 
@@ -1301,8 +1328,9 @@ def class_object(self):
 
     def auto_link_self(self, docstrings):
         name = self.object.name
-        # negative look-behind for ` . < @ <non-breaking space>
-        p = re.compile(r"(?<!(`|\.|<|@| ))\b" + name + r"\b(?! )")
+        # negative look-behind for ` or . or < or @ or <non-breaking space>
+        # and negative look-ahead for <non-breaking space> or .<alphanum>
+        p = re.compile(r"(?<!(`|\.|<|@| ))\b" + name + r"\b(?! |\.\w)")
         no_link_state = 0  # normal mode (no literal block detected)
         for i in range(len(docstrings)):
             for j in range(len(docstrings[i])):
@@ -1398,8 +1426,9 @@ def class_object(self):
 
     def auto_link_self(self, docstrings):
         name = self.object.name
-        # negative look-behind for ` or . or <
-        p = re.compile(r"(?<!(`|\.|<))\b" + name + r"\b")
+        # negative look-behind for ` or . or < or <non-breaking space>
+        # and negative look-ahead for <non-breaking space>
+        p = re.compile(r"(?<!(`|\.|<| ))\b" + name + r"\b(?! )")
         no_link_state = 0  # normal mode (no literal block detected)
         for i in range(len(docstrings)):
             for j in range(len(docstrings[i])):

tests/roots/test_autodoc/target/ClassExample.m

@@ -20,6 +20,8 @@
     end
     methods
         function mc = ClassExample(a)
+            % Links to fully qualified names package.ClassBar.foos,
+            % package.ClassBar.doBar, and ClassExample.mymethod.
             mc.a = a;
         end
 

tests/test_autodoc.py

@@ -36,7 +36,7 @@ def test_target(make_app, rootdir):
     assert len(content) == 1
     assert (
         content[0].astext()
-        == "target\n\n\n\nclass target.ClassExample\n\nBases: handle\n\nExample class\n\nClassExample Properties:\n\na - first property of ClassExample\nb - second property of ClassExample\nc - third property of ClassExample\n\nClassExample Methods:\n\nClassExample - the constructor and a reference to mymethod()\nmymethod - a method in ClassExample\n\nSee also BaseClass, baseFunction, b, unknownEntity, mymethod.\n\nProperty Summary\n\n\n\n\n\na\n\na property\n\n\n\nb\n\na property with default value\n\n\n\nc\n\na property with multiline default value\n\nMethod Summary\n\n\n\n\n\nmymethod(b)\n\nA method in ClassExample\n\nParameters\n\nb – an input to mymethod()"
+        == "target\n\n\n\nclass target.ClassExample\n\nBases: handle\n\nExample class\n\nClassExample Properties:\n\na - first property of ClassExample\nb - second property of ClassExample\nc - third property of ClassExample\n\nClassExample Methods:\n\nClassExample - the constructor and a reference to mymethod()\nmymethod - a method in ClassExample\n\nSee also BaseClass, baseFunction, b, unknownEntity, mymethod.\n\nConstructor Summary\n\n\n\n\n\nClassExample(a)\n\nLinks to fully qualified names package.ClassBar.foos,\npackage.ClassBar.doBar, and ClassExample.mymethod.\n\nProperty Summary\n\n\n\n\n\na\n\na property\n\n\n\nb\n\na property with default value\n\n\n\nc\n\na property with multiline default value\n\nMethod Summary\n\n\n\n\n\nmymethod(b)\n\nA method in ClassExample\n\nParameters\n\nb – an input to mymethod()"
     )
     assert (
         property_section.rawsource
@@ -61,7 +61,7 @@ def test_target_show_default_value(make_app, rootdir):
     assert len(content) == 1
     assert (
         content[0].astext()
-        == "target\n\n\n\nclass target.ClassExample\n\nBases: handle\n\nExample class\n\nClassExample Properties:\n\na - first property of ClassExample\nb - second property of ClassExample\nc - third property of ClassExample\n\nClassExample Methods:\n\nClassExample - the constructor and a reference to mymethod()\nmymethod - a method in ClassExample\n\nSee also BaseClass, baseFunction, b, unknownEntity, mymethod.\n\nProperty Summary\n\n\n\n\n\na\n\na property\n\n\n\nb = 10\n\na property with default value\n\n\n\nc = [10; ... 30]\n\na property with multiline default value\n\nMethod Summary\n\n\n\n\n\nmymethod(b)\n\nA method in ClassExample\n\nParameters\n\nb – an input to mymethod()"
+        == "target\n\n\n\nclass target.ClassExample\n\nBases: handle\n\nExample class\n\nClassExample Properties:\n\na - first property of ClassExample\nb - second property of ClassExample\nc - third property of ClassExample\n\nClassExample Methods:\n\nClassExample - the constructor and a reference to mymethod()\nmymethod - a method in ClassExample\n\nSee also BaseClass, baseFunction, b, unknownEntity, mymethod.\n\nConstructor Summary\n\n\n\n\n\nClassExample(a)\n\nLinks to fully qualified names package.ClassBar.foos,\npackage.ClassBar.doBar, and ClassExample.mymethod.\n\nProperty Summary\n\n\n\n\n\na\n\na property\n\n\n\nb = 10\n\na property with default value\n\n\n\nc = [10; ... 30]\n\na property with multiline default value\n\nMethod Summary\n\n\n\n\n\nmymethod(b)\n\nA method in ClassExample\n\nParameters\n\nb – an input to mymethod()"
     )
     assert (
         property_section.rawsource
@@ -110,6 +110,7 @@ def test_target_auto_link_all(make_app, rootdir):
     property_section = content[0][2][1][2][0]  # a bit fragile, I know
     method_section = content[0][2][1][2][1]  # a bit fragile, I know
     see_also_line = content[0][2][1][3]  # a bit fragile, I know
+    constructor_desc = content[0][2][1][4][0][0][1][2][1][0]  # a bit fragile, I know
     assert len(content) == 1
     assert (
         property_section.rawsource
@@ -123,6 +124,10 @@ def test_target_auto_link_all(make_app, rootdir):
         see_also_line.rawsource
         == "See also :class:`BaseClass`, :func:`baseFunction`, :attr:`b <target.ClassExample.b>`, ``unknownEntity``, :meth:`mymethod() <target.ClassExample.mymethod>`."
     )
+    assert (
+        constructor_desc.rawsource
+        == "Links to fully qualified names :attr:`package.ClassBar.foos`,\n:meth:`package.ClassBar.doBar`, and :meth:`ClassExample.mymethod`."
+    )
 
 
 @pytest.mark.skipif(sys.version_info < (3, 6), reason="requires python3.6 or higher")

tests/test_autodoc_short_links.py

@@ -37,7 +37,7 @@ def test_target(make_app, rootdir):
     assert len(content) == 1
     assert (
         content[0].astext()
-        == "target\n\n\n\nclass ClassExample\n\nBases: handle\n\nExample class\n\nClassExample Properties:\n\na - first property of ClassExample\nb - second property of ClassExample\nc - third property of ClassExample\n\nClassExample Methods:\n\nClassExample - the constructor and a reference to mymethod()\nmymethod - a method in ClassExample\n\nSee also BaseClass, baseFunction, b, unknownEntity, mymethod.\n\nProperty Summary\n\n\n\n\n\na\n\na property\n\n\n\nb\n\na property with default value\n\n\n\nc\n\na property with multiline default value\n\nMethod Summary\n\n\n\n\n\nmymethod(b)\n\nA method in ClassExample\n\nParameters\n\nb – an input to mymethod()"
+        == "target\n\n\n\nclass ClassExample\n\nBases: handle\n\nExample class\n\nClassExample Properties:\n\na - first property of ClassExample\nb - second property of ClassExample\nc - third property of ClassExample\n\nClassExample Methods:\n\nClassExample - the constructor and a reference to mymethod()\nmymethod - a method in ClassExample\n\nSee also BaseClass, baseFunction, b, unknownEntity, mymethod.\n\nConstructor Summary\n\n\n\n\n\nClassExample(a)\n\nLinks to fully qualified names package.ClassBar.foos,\npackage.ClassBar.doBar, and ClassExample.mymethod.\n\nProperty Summary\n\n\n\n\n\na\n\na property\n\n\n\nb\n\na property with default value\n\n\n\nc\n\na property with multiline default value\n\nMethod Summary\n\n\n\n\n\nmymethod(b)\n\nA method in ClassExample\n\nParameters\n\nb – an input to mymethod()"
     )
     assert (
         property_section.rawsource
@@ -62,7 +62,7 @@ def test_target_show_default_value(make_app, rootdir):
     assert len(content) == 1
     assert (
         content[0].astext()
-        == "target\n\n\n\nclass ClassExample\n\nBases: handle\n\nExample class\n\nClassExample Properties:\n\na - first property of ClassExample\nb - second property of ClassExample\nc - third property of ClassExample\n\nClassExample Methods:\n\nClassExample - the constructor and a reference to mymethod()\nmymethod - a method in ClassExample\n\nSee also BaseClass, baseFunction, b, unknownEntity, mymethod.\n\nProperty Summary\n\n\n\n\n\na\n\na property\n\n\n\nb = 10\n\na property with default value\n\n\n\nc = [10; ... 30]\n\na property with multiline default value\n\nMethod Summary\n\n\n\n\n\nmymethod(b)\n\nA method in ClassExample\n\nParameters\n\nb – an input to mymethod()"
+        == "target\n\n\n\nclass ClassExample\n\nBases: handle\n\nExample class\n\nClassExample Properties:\n\na - first property of ClassExample\nb - second property of ClassExample\nc - third property of ClassExample\n\nClassExample Methods:\n\nClassExample - the constructor and a reference to mymethod()\nmymethod - a method in ClassExample\n\nSee also BaseClass, baseFunction, b, unknownEntity, mymethod.\n\nConstructor Summary\n\n\n\n\n\nClassExample(a)\n\nLinks to fully qualified names package.ClassBar.foos,\npackage.ClassBar.doBar, and ClassExample.mymethod.\n\nProperty Summary\n\n\n\n\n\na\n\na property\n\n\n\nb = 10\n\na property with default value\n\n\n\nc = [10; ... 30]\n\na property with multiline default value\n\nMethod Summary\n\n\n\n\n\nmymethod(b)\n\nA method in ClassExample\n\nParameters\n\nb – an input to mymethod()"
     )
     assert (
         property_section.rawsource
@@ -111,6 +111,7 @@ def test_target_auto_link_all(make_app, rootdir):
     property_section = content[0][2][1][2][0]  # a bit fragile, I know
     method_section = content[0][2][1][2][1]  # a bit fragile, I know
     see_also_line = content[0][2][1][3]  # a bit fragile, I know
+    constructor_desc = content[0][2][1][4][0][0][1][2][1][0]  # a bit fragile, I know
     assert len(content) == 1
     assert (
         property_section.rawsource
@@ -124,6 +125,10 @@ def test_target_auto_link_all(make_app, rootdir):
         see_also_line.rawsource
         == "See also :class:`BaseClass`, :func:`baseFunction`, :attr:`b <ClassExample.b>`, ``unknownEntity``, :meth:`mymethod() <ClassExample.mymethod>`."
     )
+    assert (
+        constructor_desc.rawsource
+        == "Links to fully qualified names :attr:`package.ClassBar.foos`,\n:meth:`package.ClassBar.doBar`, and :meth:`ClassExample.mymethod`."
+    )
 
 
 @pytest.mark.skipif(sys.version_info < (3, 6), reason="requires python3.6 or higher")