Fix compatibility with sphinx 6 (#161)

_visit_sig_parameter_list doesn't exist in Sphinx 6 so we need to reimplement it.

.github/workflows/ci.yml

@@ -17,7 +17,6 @@ jobs:
       fail-fast: false
       matrix:
         python-version: ["3.10", "3.11", "3.12"]
-        experimental: [false]
 
     name: Python ${{ matrix.python-version}}
     steps:
@@ -56,7 +55,6 @@ jobs:
       matrix:
         python-version: ["3.12"]
         typedoc-version: ["0.25"]
-        experimental: [false]
 
     name: Python ${{ matrix.python-version}} + typedoc ${{ matrix.typedoc-version }}
     steps:
@@ -79,3 +77,36 @@ jobs:
         with:
           name: test_typedoc-results-${{ matrix.python-version }}-${{ matrix.typedoc-version }}
           path: test-results.xml
+
+  test-sphinx-versions:
+    runs-on: ubuntu-latest
+
+    continue-on-error: true
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12"]
+        sphinx-version: ["6"]
+
+    name: Test sphinx 6
+    steps:
+      - uses: actions/checkout@v3.1.0
+
+      - name: Set up Python
+        uses: actions/setup-python@v4.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Update pip and install dev requirements
+        run: |
+          python -m pip install --upgrade pip
+          pip install nox
+      - name: Test
+        run: nox -s "test_sphinx_6-${{ matrix.python-version }}"
+
+      - uses: actions/upload-artifact@v2
+        if: success() || failure()
+        with:
+          name: test_sphinx_6-${{ matrix.python-version }}
+          path: test-results.xml

.github/workflows/test_report.yml

@@ -9,7 +9,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11"]
+        python-version: ["3.10", "3.11", "3.12"]
 
     runs-on: ubuntu-latest
     steps:
@@ -23,8 +23,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11"]
-        typedoc-version: ["0.20", "0.21"]
+        python-version: ["3.12"]
+        typedoc-version: ["0.25"]
 
     runs-on: ubuntu-latest
     steps:
@@ -34,3 +34,18 @@ jobs:
           name: Test report - Python ${{ matrix.python-version}} + typedoc ${{ matrix.typedoc-version }}
           path: test-results.xml
           reporter: java-junit
+  report-sphinx:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12"]
+        sphinx-version: ["6"]
+
+    runs-on: ubuntu-latest
+    steps:
+      - uses: dorny/test-reporter@v1.6.0
+        with:
+          artifact: test_sphinx_6-${{ matrix.python-version }}
+          name: Test report - Sphinx 6
+          path: test-results.xml
+          reporter: java-junit

noxfile.py

@@ -33,3 +33,16 @@ def test_typedoc(session: Session, typedoc: str) -> None:
             "npm", "i", "--no-save", "jsdoc@4.0.0", f"typedoc@{typedoc}", external=True
         )
     session.run("pytest", "--junitxml=test-results.xml", "-k", "not js")
+
+
+@nox.session(python=["3.12"])
+def test_sphinx_6(session: Session) -> None:
+    session.install("sphinx<7")
+    session.install("-r", "requirements_dev.txt")
+    venvroot = Path(session.bin).parent
+    (venvroot / "node_modules").mkdir()
+    with session.chdir(venvroot):
+        session.run(
+            "npm", "i", "--no-save", "jsdoc@4.0.0", "typedoc@0.25", external=True
+        )
+    session.run("pytest", "--junitxml=test-results.xml", "-k", "not js")

sphinx_js/directives.py

@@ -33,6 +33,7 @@
 from sphinx.locale import _
 from sphinx.util.docfields import GroupedField, TypedField
 from sphinx.writers.html5 import HTML5Translator
+from sphinx.writers.text import TextTranslator
 
 from .renderers import (
     AutoAttributeRenderer,
@@ -272,22 +273,58 @@ def astext(self) -> str:
         return f"<{nodes.FixedTextElement.astext(self)}>"
 
 
-def visit_desc_js_type_parameter_list(
+def html5_visit_desc_js_type_parameter_list(
     self: HTML5Translator, node: nodes.Element
 ) -> None:
     """Define the html/text rendering for desc_js_type_parameter_list. Based on
     sphinx.writers.html5.visit_desc_type_parameter_list
     """
-    self._visit_sig_parameter_list(node, addnodes.desc_parameter, "<", ">")
+    if hasattr(self, "_visit_sig_parameter_list"):
+        # Sphinx 7
+        return self._visit_sig_parameter_list(node, addnodes.desc_parameter, "<", ">")
+    # Sphinx <7
+    self.body.append('<span class="sig-paren">&lt;</span>')
+    self.first_param = 1
+    self.optional_param_level = 0
+    # How many required parameters are left.
+    self.required_params_left = sum(
+        [isinstance(c, addnodes.desc_parameter) for c in node.children]
+    )
+    self.param_separator = node.child_text_separator
 
 
-def depart_desc_js_type_parameter_list(
+def html5_depart_desc_js_type_parameter_list(
     self: HTML5Translator, node: nodes.Element
 ) -> None:
     """Define the html/text rendering for desc_js_type_parameter_list. Based on
     sphinx.writers.html5.depart_desc_type_parameter_list
     """
-    self._depart_sig_parameter_list(node)
+    if hasattr(self, "_depart_sig_parameter_list"):
+        # Sphinx 7
+        return self._depart_sig_parameter_list(node)
+    # Sphinx <7
+    self.body.append('<span class="sig-paren">&gt;</span>')
+
+
+def text_visit_desc_js_type_parameter_list(
+    self: TextTranslator, node: nodes.Element
+) -> None:
+    if hasattr(self, "_visit_sig_parameter_list"):
+        # Sphinx 7
+        return self._visit_sig_parameter_list(node, addnodes.desc_parameter, "<", ">")
+    # Sphinx <7
+    self.add_text("<")
+    self.first_param = 1  # type:ignore[attr-defined]
+
+
+def text_depart_desc_js_type_parameter_list(
+    self: TextTranslator, node: nodes.Element
+) -> None:
+    if hasattr(self, "_depart_sig_parameter_list"):
+        # Sphinx 7
+        return self._depart_sig_parameter_list(node)
+    # Sphinx <7
+    self.add_text(">")
 
 
 def add_param_list_to_signode(signode: desc_signature, params: str) -> None:
@@ -457,6 +494,12 @@ def add_directives(app: Sphinx) -> None:
     app.add_role_to_domain("js", "typealias", JSXRefRole())
     app.add_node(
         desc_js_type_parameter_list,
-        html=(visit_desc_js_type_parameter_list, depart_desc_js_type_parameter_list),
-        text=(visit_desc_js_type_parameter_list, depart_desc_js_type_parameter_list),
+        html=(
+            html5_visit_desc_js_type_parameter_list,
+            html5_depart_desc_js_type_parameter_list,
+        ),
+        text=(
+            text_visit_desc_js_type_parameter_list,
+            text_depart_desc_js_type_parameter_list,
+        ),
     )

tests/testing.py

@@ -53,10 +53,12 @@ def _file_contents(self, filename):
         ) as file:
             return file.read()
 
-    def _file_contents_eq(self, filename, contents):
+    def _file_contents_eq(self, filename, expected_contents):
         __tracebackhide__ = True
-        print(self._file_contents(filename))
-        assert self._file_contents(filename) == contents
+        contents = self._file_contents(filename)
+        # Fix a difference between sphinx v6 and v7
+        contents = contents.replace(" --\n", "\n")
+        assert contents == expected_contents
 
 
 class JsDocTestCase(ThisDirTestCase):