Merge pull request #71 from markstory/fix-regression

Fix regressions in cross linking

Author: markstory

.github/workflows/ci.yml

@@ -10,9 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        # Builds are failing with py3.9+ because sphinx templates are different.
-        # python: ['3.7', '3.8', '3.9', '3.10', '3.11']
-        python: ['3.7', '3.8']
+        python: ['3.10', '3.11', '3.12']
       fail-fast: false
 
     permissions:
@@ -33,33 +31,21 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         pip install -r requirements.txt
-        pip install -r test/requirements.txt
+        pip install -r requirements-test.txt
         pip install .
 
     - name: Build Unit Tests
       run: |
-        cd test
-        find . -name '*.html' -exec rm {} \;
-
-        sed -i 's~, "log\.md"~~' conf.py
-        make html SPHINXOPTS='' 2>&1 | tee log.txt
-        git restore conf.py
-
-        (cd _build/html && rm genindex.html index.html search.html php-modindex.html)
-        (cd _build/html && find . -name '*.html' -exec sh -c 'xmllint {} --xpath '"'"'//div[@role="main"]'"'"' | xmllint --format - > ../../{}' \;)
-        sed -i -r 's~.*/(test/)~\1~;t;d' log.txt
+        cd test/unit
+        make clean
+        make html SPHINXOPTS='-W'
+        make comparehtml
 
     - name: Apply Coding Style
       if: matrix.python == '3.11'
       run: |
         pip install black
-        python -m black .
-
-    - name: Diff Unit Tests Output and Coding Style
-      run: |
-        cd test
-        rm -r _build
-        git add . -N && git diff --exit-code
+        python -m black --diff --check .
 
     - name: Push Unit Tests Output
       if: failure() && github.repository_owner != 'markstory' && matrix.python == '3.11'
@@ -73,26 +59,22 @@ jobs:
         commit_user_email: bot@example.com
         commit_author: Bot <bot@example.com>
 
-    - name: Build Unit Tests with '-W' option
+    - name: Build myst integration tests
       run: |
-        cd test
+        cd test/myst
         make html SPHINXOPTS='-W'
 
-        sed -i 's~, "log\.md"~~' conf.py
-        ! make html SPHINXOPTS='-W' || (echo 'Unexpected zero exit code'; false)
-        git restore conf.py
-
     - name: Build Unit Tests with toc show_parents=hide
       run: |
-        cd test
+        cd test/unit
         make html SPHINXOPTS='-W -D toc_object_entries_show_parents=hide'
 
     - name: Build Unit Tests with toc show_parents=domain
       run: |
-        cd test
+        cd test/unit
         make html SPHINXOPTS='-W -D toc_object_entries_show_parents=domain'
 
     - name: Build Unit Tests with toc show_parents=all
       run: |
-        cd test
+        cd test/unit
         make html SPHINXOPTS='-W -D toc_object_entries_show_parents=all'

.gitignore

@@ -1,7 +1,7 @@
 dist/
 build/
 doc/_build
-test/_build
+test/*/_build
 *.pyc
 *.egg-info
 .DS_Store

requirements-test.txt

@@ -0,0 +1 @@
+myst-parser

setup.py

@@ -28,14 +28,14 @@
 """
 
 setup(
-    name='sphinxcontrib-phpdomain',
-    version='0.12.0',
-    url='https://github.com/markstory/sphinxcontrib-phpdomain',
-    download_url='http://pypi.python.org/pypi/sphinxcontrib-phpdomain',
-    license='BSD',
-    author='Mark Story',
-    author_email='mark@mark-story.com',
-    description='Sphinx extension to enable documenting PHP code',
+    name="sphinxcontrib-phpdomain",
+    version="0.12.0",
+    url="https://github.com/markstory/sphinxcontrib-phpdomain",
+    download_url="http://pypi.python.org/pypi/sphinxcontrib-phpdomain",
+    license="BSD",
+    author="Mark Story",
+    author_email="mark@mark-story.com",
+    description="Sphinx extension to enable documenting PHP code",
     long_description=long_desc,
     project_urls={
         "Documentation": "https://markstory.github.io/sphinxcontrib-phpdomain/",

sphinxcontrib/phpdomain.py

@@ -1,11 +1,12 @@
 """
-    Sphinx PHP domain.
-    
-    The PHP domain. Based off of the rubydomain by SHIBUKAWA Yoshiki
+Sphinx PHP domain.
 
-    :copyright: Copyright 2016 by Mark Story
-    :license: BSD, see LICENSE for details.
+The PHP domain. Based off of the rubydomain by SHIBUKAWA Yoshiki
+
+:copyright: Copyright 2016 by Mark Story
+:license: BSD, see LICENSE for details.
 """
+
 import re
 import inspect
 
@@ -70,9 +71,9 @@ def throw_if_false(fromdocnode, value, message: str):
 
 separators = {
     "global": None,
-    "namespace": None,
-    "function": None,
-    "interface": None,
+    "namespace": NS,
+    "function": NS,
+    "interface": NS,
     "class": None,
     "trait": None,
     "enum": None,
@@ -229,17 +230,20 @@ def handle_signature(self, sig, signode):
         )
         separator = separators[self.objtype]
 
-        if "::" in name_prefix:
+        classname = self.env.temp_data.get("php:class")
+        # Method declared as Class::methodName
+        if not classname and "::" in name_prefix:
             classname = name_prefix.rstrip("::")
-        else:
-            classname = self.env.temp_data.get("php:class")
 
-        if self.objtype == "global":
+        if self.objtype == "global" or self.objtype == "function":
+            add_module = False
             namespace = None
             classname = None
             fullname = name
         else:
+            add_module = True
             if name_prefix:
+                classname = classname.rstrip("::")
                 fullname = name_prefix + name
 
             # Currently in a class, but not creating another class,
@@ -259,6 +263,14 @@ def handle_signature(self, sig, signode):
                 classname = ""
                 fullname = name
 
+            # A leading \ means the name is fully qualified
+            # and should not inherit the current namespace.
+            if fullname.startswith(NS) and namespace:
+                add_module = False
+                name = name[1:]
+                fullname = fullname[1:]
+                namespace = None
+
         signode["namespace"] = namespace
         signode["class"] = self.class_name = classname
         signode["fullname"] = fullname
@@ -279,15 +291,21 @@ def handle_signature(self, sig, signode):
                 name_prefix = namespace + NS + name_prefix
             signode += addnodes.desc_addname(name_prefix, name_prefix)
 
-        elif (
-            namespace
-            and not self.env.temp_data.get("php:in_class", False)
-            and self.env.config.add_module_names
-        ):
-            nodetext = namespace + NS
-            signode += addnodes.desc_addname(nodetext, nodetext)
+        elif add_module and self.env.config.add_module_names:
+            if self.objtype == "global":
+                nodetext = ""
+                signode += addnodes.desc_addname(nodetext, nodetext)
+            else:
+                namespace = self.options.get(
+                    "namespace", self.env.temp_data.get("php:namespace")
+                )
+
+                if namespace and not self.env.temp_data.get("php:in_class", False):
+                    nodetext = namespace + NS
+                    signode += addnodes.desc_addname(nodetext, nodetext)
 
         signode += addnodes.desc_name(name, name)
+
         if not arglist:
             if self.needs_arglist():
                 # for callables, add an empty parameter list
@@ -603,26 +621,18 @@ class PhpXRefRole(XRefRole):
 
     def process_link(self, env, refnode, has_explicit_title, title, target):
         if not has_explicit_title:
-            # If the first char is '~' don't display the leading namespace & class.
-            if target.startswith("~"):  # only has a meaning for the title
-                target = title[1:]
-            if title.startswith("~"):
-                title = title[1:]
-                title = re.sub(r"^[\w\\]+::", "", title)
-
-            if title.startswith(NS):
-                title = title[1:]
+            if title.startswith("::"):
+                title = title[2:]
+            target = target.lstrip("~")  # only has a meaning for the title
 
-        reftype = refnode.attributes["reftype"]
-        if reftype == "global":
-            namespace = None
-            classname = None
-        else:
-            namespace = env.temp_data.get("php:namespace")
-            classname = env.temp_data.get("php:class")
+            # If the first char is ~ don't display the leading namespace & class.
+            if title.startswith("~"):
+                m = re.search(r"(?:.+[:]{2}|(?:.*?\\{1,2})+)?(.*)\Z", title)
+                if m:
+                    title = m.group(1)
 
-        refnode["php:namespace"] = namespace
-        refnode["php:class"] = classname
+        refnode["php:namespace"] = env.temp_data.get("php:namespace")
+        refnode["php:class"] = env.temp_data.get("php:class")
 
         return title, target
 
@@ -814,76 +824,79 @@ def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
         else:
             namespace = node.get("php:namespace")
             clsname = node.get("php:class")
-            name, obj = self.find_obj(env, node, namespace, clsname, target, typ)
+            searchorder = node.hasattr("refspecific") and 1 or 0
+            name, obj = self.find_obj(
+                env, node, namespace, clsname, target, typ, searchorder
+            )
             if not obj:
                 return None
             else:
                 return make_refnode(builder, fromdocname, obj[0], name, contnode, name)
 
-    def find_obj(self, env, fromdocnode, namespace, classname, name, type):
+    def find_obj(
+        self, env, fromdocnode, namespace, classname, name, type, searchorder=0
+    ):
         """
         Find a PHP object for "name", using the given namespace and classname.
         """
         # strip parenthesis
         if name[-2:] == "()":
             name = name[:-2]
 
+        if not name:
+            return None, None
+
         objects = self.data["objects"]
 
-        if name.startswith(NS):
-            absname = name[1:]
+        newname = None
+        if searchorder == 1:
+            if (
+                namespace
+                and classname
+                and namespace + NS + classname + "::" + name in objects
+            ):
+                newname = namespace + NS + classname + "::" + name
+            elif namespace and namespace + NS + name in objects:
+                newname = namespace + NS + name
+            elif namespace and namespace + NS + name in objects:
+                newname = namespace + NS + name
+            elif classname and classname + "::" + name in objects:
+                newname = classname + "." + name
+            elif classname and classname + "::$" + name in objects:
+                newname = classname + "::$" + name
+            elif name in objects:
+                newname = name
         else:
-            absname = (namespace + NS if namespace else "") + name
-
-            if absname not in objects and name in objects:
-                # constants/functions can be namespaced, but allow fallback to global namespace the same way as PHP does
-                name_type = objects[name][1]
-                if (
-                    (name_type == "function" or name_type == "const")
-                    and NS not in name
-                    and "::" not in name
-                ):
-                    absname = name
-                else:
-                    if namespace and name.startswith(namespace + NS):
-                        log_info(
-                            fromdocnode,
-                            f"Target {absname} not found - did you mean to write {name[len(namespace + NS):]}?",
-                        )
-                    else:
-                        log_info(
-                            fromdocnode,
-                            f"Target {absname} not found - did you mean to write {NS + name}?",
-                        )
-                    absname = name  # fallback for BC, might be removed in the next major release
-
-        if absname in objects:
-            return absname, objects[absname]
-
-        # PHP reserved keywords are never resolved using NS and ignore them when not defined
-        if name not in [
-            "array",
-            "bool",
-            "callable",
-            "false",
-            "float",
-            "int",
-            "iterable",
-            "mixed",
-            "never",
-            "null",
-            "object",
-            "parent",
-            "resource",
-            "self",
-            "static",
-            "string",
-            "true",
-            "void",
-        ]:
-            log_info(fromdocnode, f"Target {absname} not found")
-
-        return None, None
+            if name in objects:
+                newname = name
+            elif classname and classname + "::" + name in objects:
+                newname = classname + "::" + name
+            elif classname and classname + "::$" + name in objects:
+                newname = classname + "::$" + name
+            elif namespace and namespace + NS + name in objects:
+                newname = namespace + NS + name
+            elif (
+                namespace
+                and classname
+                and namespace + NS + classname + "::" + name in objects
+            ):
+                newname = namespace + NS + classname + "::" + name
+            elif (
+                namespace
+                and classname
+                and namespace + NS + classname + "::$" + name in objects
+            ):
+                newname = namespace + NS + classname + "::$" + name
+            # special case: object methods
+            elif (
+                type in ("func", "meth")
+                and "::" not in name
+                and "object::" + name in objects
+            ):
+                newname = "object::" + name
+        if newname is None:
+            return None, None
+        return newname, objects[newname]
 
     def get_objects(self):
         for ns, info in self.data["namespaces"].items():