ENH: Compatibility with docutils>=0.18 (from support with sphinx>=5) (#…

…60)

* pre-commit file update

* removing python 3.6

* removing python 3.6

* updated tests

* sphinx version

* sphinx versions

* specific test files for sphinx4

* remove py37 support

* update CI

* removing python3.7

* updating tests for sphinx5

Co-authored-by: mmcky <[email protected]>

.github/workflows/ci.yml

@@ -13,17 +13,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
-      - name: Set up Python 3.8
+      - name: Set up Python 3.9
         uses: actions/setup-python@v1
         with:
-          python-version: 3.8
+          python-version: 3.9
       - uses: pre-commit/[email protected]
 
   tests:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8]
+        python-version: [3.8, 3.9]
     steps:
       - uses: actions/checkout@v2
       - name: Set up Python ${{ matrix.python-version }}
@@ -40,10 +40,10 @@ jobs:
       - name: Create cov
         run: coverage xml
       - name: Upload to Codecov
-        if: matrix.python-version == 3.7
+        if: matrix.python-version == 3.8
         uses: codecov/codecov-action@v1
         with:
-          name: sphinx-exercise-pytest-py3.7
+          name: sphinx-exercise-pytest-py3.8
           flags: pytests
           file: ./coverage.xml
           fail_ci_if_error: true
@@ -53,10 +53,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
-      - name: Set up Python 3.8
+      - name: Set up Python 3.9
         uses: actions/setup-python@v1
         with:
-          python-version: 3.8
+          python-version: 3.9
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
@@ -75,10 +75,10 @@ jobs:
     steps:
       - name: Checkout source
         uses: actions/checkout@v2
-      - name: Set up Python 3.7
+      - name: Set up Python 3.9
         uses: actions/setup-python@v1
         with:
-          python-version: 3.7
+          python-version: 3.9
       - name: Build package
         run: |
           pip install wheel

.pre-commit-config.yaml

@@ -15,19 +15,19 @@ exclude: >
 
 repos:
 
-  - repo: git://github.com/pre-commit/pre-commit-hooks
-    rev: v2.2.3
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.3.0
     hooks:
       - id: check-yaml
       - id: end-of-file-fixer
       - id: trailing-whitespace
 
-  - repo: https://gitlab.com/pycqa/flake8
-    rev: 3.7.9
+  - repo: https://github.com/PyCQA/flake8
+    rev: 5.0.4
     hooks:
     - id: flake8
 
   - repo: https://github.com/psf/black
-    rev: 20.8b1
+    rev: 22.8.0
     hooks:
       - id: black

docs/requirements.txt

@@ -1,3 +1,3 @@
-sphinx>=3.0
+sphinx>=4,<6
 sphinx-book-theme
 myst-nb

docs/runtime.txt

@@ -1 +1 @@
-3.7
+3.8

setup.py

@@ -18,21 +18,23 @@
 
 # Define all extras
 extras = {
-    "code_style": ["flake8<3.8.0,>=3.7.0", "black", "pre-commit==1.17.0"],
+    "code_style": ["flake8<3.8.0,>=3.7.0", "black", "pre-commit"],
     "testing": [
         "coverage",
         "pytest>=3.6,<4",
         "pytest-cov",
         "pytest-regressions",
         "beautifulsoup4",
-        "myst-nb",
+        "myst-nb~=0.17.1",
+        "sphinx>=4,<6",
+        "docutils>=0.15,<0.19",
         "texsoup",
         "matplotlib",
     ],
     "rtd": [
-        "sphinx>=3.0",
+        "sphinx>=4,<6",
         "sphinx-book-theme",
-        "myst-nb",
+        "myst-nb~=0.17.1",
     ],
 }
 
@@ -41,7 +43,7 @@
 setup(
     name="sphinx-exercise",
     version=VERSION,
-    python_requires=">=3.6",
+    python_requires=">=3.8",
     author="QuantEcon",
     author_email="[email protected]",
     url=BASE_URL,
@@ -55,7 +57,7 @@
     long_description_content_type="text/markdown",
     license="BSD",
     packages=find_packages(),
-    install_requires=["docutils>=0.15", "sphinx", "sphinx-book-theme"],
+    install_requires=["sphinx>=4", "sphinx-book-theme"],
     extras_require=extras,
     include_package_data=True,
     classifiers=[
@@ -67,9 +69,8 @@
         "License :: OSI Approved :: MIT License",
         "Natural Language :: English",
         "Operating System :: OS Independent",
-        "Programming Language :: Python :: 3.6",
-        "Programming Language :: Python :: 3.7",
         "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
         "Programming Language :: Python",
         "Topic :: Documentation :: Sphinx",
         "Topic :: Documentation",

sphinx_exercise/__init__.py

@@ -66,7 +66,7 @@
 
 
 def purge_exercises(app: Sphinx, env: BuildEnvironment, docname: str) -> None:
-    """ Purge sphinx_exercise registry """
+    """Purge sphinx_exercise registry"""
 
     if not hasattr(env, "sphinx_exercise_registry"):
         return
@@ -85,7 +85,7 @@ def purge_exercises(app: Sphinx, env: BuildEnvironment, docname: str) -> None:
 def merge_exercises(
     app: Sphinx, env: BuildEnvironment, docnames: Set[str], other: BuildEnvironment
 ) -> None:
-    """ Merge sphinx_exercise_registry """
+    """Merge sphinx_exercise_registry"""
 
     if not hasattr(env, "sphinx_exercise_registry"):
         env.sphinx_exercise_registry = {}
@@ -109,7 +109,7 @@ def init_numfig(app: Sphinx, config: Config) -> None:
 
 
 def copy_asset_files(app: Sphinx, exc: Union[bool, Exception]):
-    """ Copies required assets for formating in HTML """
+    """Copies required assets for formating in HTML"""
 
     static_path = (
         Path(__file__).parent.joinpath("assets", "html", "exercise.css").absolute()

sphinx_exercise/directive.py

@@ -32,7 +32,7 @@
 
 class SphinxExerciseBaseDirective(SphinxDirective):
     def duplicate_labels(self, label):
-        """ Check for duplicate labels """
+        """Check for duplicate labels"""
 
         if not label == "" and label in self.env.sphinx_exercise_registry.keys():
             docpath = self.env.doc2path(self.env.docname)

sphinx_exercise/transforms.py

@@ -28,7 +28,7 @@ class CheckGatedDirectives(SphinxTransform):
     default_priority = 1
 
     def check_structure(self, registry):
-        """ Check Structure of the Gated Registry"""
+        """Check Structure of the Gated Registry"""
         error = False
         docname = self.env.docname
         if docname in registry:
@@ -111,7 +111,7 @@ def apply(self):
                     new_node += child
             # Collect nodes attached to the Parent Node until :solution-end:
             content = docutils.nodes.section(
-                ids="solution-content"
+                ids=["solution-content"]
             )  # TODO: should id be classes?
             for child in parent.children[parent_start + 1 : parent_end]:
                 content += child

tests/conftest.py

@@ -27,14 +27,24 @@ def read(app):
 
 @pytest.fixture
 def get_sphinx_app_doctree(file_regression):
-    def read(app, docname="index", resolve=False, regress=False, flatten_outdir=False):
+    def read(
+        app,
+        docname="index",
+        resolve=False,
+        regress=False,
+        flatten_outdir=False,
+        sphinx_version=False,
+    ):
         if resolve:
             doctree = app.env.get_and_resolve_doctree(docname, app.builder)
             extension = ".resolved.xml"
         else:
             doctree = app.env.get_doctree(docname)
             extension = ".xml"
 
+        if sphinx_version:
+            extension = sphinx_version + extension
+
         # convert absolute filenames
         for node in doctree.traverse(lambda n: "source" in n):
             node["source"] = Path(node["source"]).name

tests/test_build.py

@@ -37,4 +37,4 @@ def test_warnings(app, warnings, wmsg):
     build_path = app.srcdir.joinpath("_build")
     shutil.rmtree(build_path)
     app.build()
-    assert wmsg in warnings(app)
+    assert wmsg in warnings(app).replace("'", "")

tests/test_exercise/_enum_mathtitle_label.html

@@ -1,6 +1,6 @@
 <div class="exercise admonition" id="test-exc-label-math">
 <p class="admonition-title"><span class="caption-number">Exercise 1 </span> (Test <span class="math notranslate nohighlight">\(\mathbb{R}\)</span>)</p>
-<div class="section" id="exercise-content">
+<section id="exercise-content">
 <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
-</div>
+</section>
 </div>

tests/test_exercise/_enum_notitle_label.html

@@ -1,6 +1,6 @@
 <div class="exercise admonition" id="text-exc-notitle">
 <p class="admonition-title"><span class="caption-number">Exercise 2 </span></p>
-<div class="section" id="exercise-content">
+<section id="exercise-content">
 <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
-</div>
+</section>
 </div>

tests/test_exercise/_enum_title_class_label.html

@@ -1,6 +1,6 @@
 <div class="exercise test-exc admonition" id="test-exc-label">
 <p class="admonition-title"><span class="caption-number">Exercise 3 </span> (Test exercise directive)</p>
-<div class="section" id="exercise-content">
+<section id="exercise-content">
 <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
-</div>
+</section>
 </div>

tests/test_exercise/_enum_title_nolabel.html

@@ -1,6 +1,6 @@
 <div class="exercise admonition" id="exercise/_enum_title_nolabel-exercise-0">
 <p class="admonition-title"><span class="caption-number">Exercise 4 </span> (Test exercise directive)</p>
-<div class="section" id="exercise-content">
+<section id="exercise-content">
 <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
-</div>
+</section>
 </div>

tests/test_exercise/_unenum_mathtitle_label.html

@@ -1,6 +1,6 @@
 <div class="exercise admonition" id="unen-exc-label-math">
 <p class="admonition-title">Exercise (Test <span class="math notranslate nohighlight">\(\mathbb{R}\)</span>)</p>
-<div class="section" id="exercise-content">
+<section id="exercise-content">
 <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
-</div>
+</section>
 </div>

tests/test_exercise/_unenum_notitle_label.html

@@ -1,6 +1,6 @@
 <div class="exercise admonition" id="unen-exc-notitle">
 <p class="admonition-title">Exercise</p>
-<div class="section" id="exercise-content">
+<section id="exercise-content">
 <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
-</div>
+</section>
 </div>

tests/test_exercise/_unenum_title_class_label.html

@@ -1,6 +1,6 @@
 <div class="exercise unen-exc admonition" id="unen-exc-label">
 <p class="admonition-title">Exercise (Test exercise directive)</p>
-<div class="section" id="exercise-content">
+<section id="exercise-content">
 <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
-</div>
+</section>
 </div>

tests/test_exercise/_unenum_title_nolabel.html

@@ -1,6 +1,6 @@
 <div class="exercise admonition" id="exercise/_unenum_title_nolabel-exercise-0">
 <p class="admonition-title">Exercise (Test exercise directive)</p>
-<div class="section" id="exercise-content">
+<section id="exercise-content">
 <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
-</div>
+</section>
 </div>

tests/test_gateddirective.py

@@ -1,11 +1,14 @@
 import os
 import pytest
 import shutil
+import sphinx
 from bs4 import BeautifulSoup
 from sphinx.errors import ExtensionError
 
 from sphinx.testing.util import strip_escseq
 
+SPHINX_VERSION = f".sphinx{sphinx.version_info[0]}"
+
 
 @pytest.mark.sphinx("html", testroot="gateddirective")
 @pytest.mark.parametrize("docname", ["exercise-gated.html"])
@@ -48,7 +51,9 @@ def test_gated_solution_build(app, docname, file_regression):
     solution_directives = soup.select("div.solution")
     for idx, sd in enumerate(solution_directives):
         basename = docname.split(".")[0] + f"-{idx}"
-        file_regression.check(str(sd), basename=basename, extension=".html")
+        file_regression.check(
+            str(sd), basename=basename, extension=f"{SPHINX_VERSION}.html"
+        )
 
 
 @pytest.mark.sphinx("html", testroot="gateddirective")
@@ -60,10 +65,7 @@ def test_gated_solution_doctree(app, docname, get_sphinx_app_doctree):
     # Test
     app.build()
     get_sphinx_app_doctree(
-        app,
-        docname,
-        resolve=False,
-        regress=True,
+        app, docname, resolve=False, regress=True, sphinx_version=SPHINX_VERSION
     )
 
 

tests/test_gateddirective/exercise-gated-0.html

@@ -1,9 +1,9 @@
 <div class="exercise admonition" id="gated-exercise-1">
 <p class="admonition-title"><span class="caption-number">Exercise 3 </span></p>
-<div class="section" id="exercise-content">
+<section id="exercise-content">
 <p>Replicate this figure using matplotlib</p>
-<div class="figure align-default">
+<figure class="align-default">
 <img alt="_images/sphx_glr_cohere_001_2_0x.png" src="_images/sphx_glr_cohere_001_2_0x.png"/>
-</div>
-</div>
+</figure>
+</section>
 </div>

tests/test_gateddirective/exercise-gated-1.html

@@ -1,8 +1,8 @@
 <div class="exercise admonition" id="gated-exercise-2">
 <p class="admonition-title"><span class="caption-number">Exercise 4 </span> (Replicate Matplotlib Plot)</p>
-<div class="section" id="exercise-content">
-<div class="figure align-default">
+<section id="exercise-content">
+<figure class="align-default">
 <img alt="_images/sphx_glr_cohere_001_2_0x.png" src="_images/sphx_glr_cohere_001_2_0x.png"/>
-</div>
-</div>
+</figure>
+</section>
 </div>

tests/test_gateddirective/exercise-gated.xml

@@ -1,5 +1,5 @@
 <document source="exercise-gated.md">
-    <section classes="tex2jax_ignore mathjax_ignore" ids="gated-exercises" names="gated\ exercises">
+    <section ids="gated-exercises" names="gated\ exercises">
         <title>
             Gated Exercises
         <paragraph>