⬆️ Support Sphinx v5, drop v3 (#74)

Author: chrisjsewell

.github/workflows/ci.yml

@@ -55,6 +55,28 @@ jobs:
         file: ./coverage.xml
         fail_ci_if_error: true
 
+  tests-sphinx4:
+
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.7", "3.10"]
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .[testing] sphinx~=4.5
+    - name: Run pytest
+      run: pytest
+
   publish:
 
     name: Publish to PyPi

pyproject.toml

@@ -27,23 +27,23 @@ classifiers = [
 ]
 keywords = ["sphinx", "extension", "material design", "web components"]
 requires-python = ">=3.7"
-dependencies = ["sphinx>=3,<5"]
+dependencies = ["sphinx>=4,<6"]
 
 [project.urls]
 Homepage = "https://github.com/executablebooks/sphinx-design"
 Documentation = "https://sphinx-design.readthedocs.io"
 
 [project.optional-dependencies]
 code_style = ["pre-commit~=2.12"]
-rtd = ["myst-parser~=0.17.0"]
+rtd = ["myst-parser~=0.18.0"]
 testing = [
-    "myst-parser~=0.17.0",
-    "pytest~=6.2",
+    "myst-parser~=0.18.0",
+    "pytest~=7.1",
     "pytest-cov",
     "pytest-regressions",
 ]
-theme_furo = ["furo==2022.04.07"]
-theme_pydata = ["pydata-sphinx-theme~=0.8.1"]
+theme_furo = ["furo>=2022.06.04,<2022.07"]
+theme_pydata = ["pydata-sphinx-theme~=0.9.0"]
 theme_rtd = ["sphinx-rtd-theme~=1.0"]
 theme_sbt = ["sphinx-book-theme~=0.3.0"]
 

sphinx_design/_compat.py

@@ -0,0 +1,11 @@
+"""Helpers for cross compatibility across dependency versions."""
+from typing import Callable, Iterable
+
+from docutils.nodes import Element
+
+
+def findall(node: Element) -> Callable[..., Iterable[Element]]:
+    """Iterate through"""
+    # findall replaces traverse in docutils v0.18
+    # note a difference is that findall is an iterator
+    return getattr(node, "findall", node.traverse)

sphinx_design/cards.py

@@ -9,6 +9,7 @@
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.logging import getLogger
 
+from ._compat import findall
 from .shared import (
     WARNING_TYPE,
     PassthroughTextElement,
@@ -229,11 +230,11 @@ def _create_component(
     @staticmethod
     def add_card_child_classes(node):
         """Add classes to specific child nodes."""
-        for para in node.traverse(nodes.paragraph):
+        for para in findall(node)(nodes.paragraph):
             para["classes"] = ([] if "classes" not in para else para["classes"]) + [
                 "sd-card-text"
             ]
-        # for title in node.traverse(nodes.title):
+        # for title in findall(node)(nodes.title):
         #     title["classes"] = ([] if "classes" not in title else title["classes"]) + [
         #         "sd-card-title"
         #     ]

sphinx_design/dropdown.py

@@ -14,6 +14,7 @@
     margin_option,
 )
 
+from ._compat import findall
 from .icons import get_octicon, list_octicons
 
 
@@ -217,7 +218,7 @@ def run(self):
                 children=body_children,
             )
             if use_card:
-                for para in body_node.traverse(nodes.paragraph):
+                for para in findall(body_node)(nodes.paragraph):
                     para["classes"] = ([] if "classes" in para else para["classes"]) + [
                         "sd-card-text"
                     ]

sphinx_design/extension.py

@@ -10,6 +10,7 @@
 from sphinx.util.docutils import SphinxDirective
 
 from . import compiled as static_module
+from ._compat import findall
 from .article_info import setup_article_info
 from .badges_buttons import setup_badges_and_buttons
 from .cards import setup_cards
@@ -143,15 +144,15 @@ class AddFirstTitleCss(SphinxTransform):
 
     def apply(self):
         hide = False
-        for docinfo in self.document.traverse(nodes.docinfo):
-            for name in docinfo.traverse(nodes.field_name):
+        for docinfo in findall(self.document)(nodes.docinfo):
+            for name in findall(docinfo)(nodes.field_name):
                 if name.astext() == "sd_hide_title":
                     hide = True
                     break
             break
         if not hide:
             return
-        for section in self.document.traverse(nodes.section):
+        for section in findall(self.document)(nodes.section):
             if isinstance(section.children[0], nodes.title):
                 if "classes" in section.children[0]:
                     section.children[0]["classes"].append("sd-d-none")

tests/conftest.py

@@ -7,6 +7,7 @@
 from sphinx.testing.path import path as sphinx_path
 from sphinx.testing.util import SphinxTestApp
 
+from sphinx_design._compat import findall
 from sphinx_design.tabs import TabSetHtmlTransform
 
 pytest_plugins = "sphinx.testing.fixtures"
@@ -46,7 +47,7 @@ def get_doctree(
         if post_transforms:
             self.app.env.apply_post_transforms(doctree, docname)
         # make source path consistent for test comparisons
-        for node in doctree.traverse(include_self=True):
+        for node in findall(doctree)(include_self=True):
             if not ("source" in node and node["source"]):
                 continue
             node["source"] = Path(node["source"]).relative_to(self.src_path).as_posix()

tox.ini

@@ -9,7 +9,7 @@ envlist = py38
 [testenv]
 usedevelop = true
 
-[testenv:py{36,37,38,39}]
+[testenv:py{37,38,39,310}]
 description = Run unit tests with this Python version
 extras =
     testing