Merge pull request #927 from bsipocz/MAINT_sphinx_dev

MAINT: adding sphinx9 and python3.14 support and bumping minimum sphinx to 7 and python to 3.11

Author: bsipocz

.github/workflows/tests.yml

@@ -30,9 +30,9 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
         # Test last 2 major releases of Sphinx; regression fixtures target the latest.
-        sphinx: ["~=7.0", "~=8.0"]
+        sphinx: ["~=7.0", "~=8.0", "~=9.0"]
         include:
         - os: windows-latest
           python-version: 3.13
@@ -109,7 +109,7 @@ jobs:
         from pathlib import Path
         import re
         text = Path("./warnings.txt").read_text().strip()
-        expected_warning_patterns = [r"kitchen\-sink", r"urllib/parse\.py", r"Glyph 10024 .*? missing from current font"]
+        expected_warning_patterns = [r"kitchen\-sink", r"urllib/parse\.py", r"Glyph 10024 .*? missing from current font", r"list assignment index out of range \[autodoc\]"]
         print("\n=== Sphinx Warnings ===\n\n" + text)  # Print just for reference so we can look at the logs
         unexpected = [l for l in text.splitlines() if not any(re.search(p, l) for p in expected_warning_patterns)]
         assert len(unexpected) == 0, unexpected

.readthedocs.yml

@@ -4,7 +4,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.10"
+    python: "3.12"
 
 python:
   install:

docs/conf.py

@@ -190,6 +190,8 @@
 linkcheck_ignore = [
     "http://someurl/release",  # This is a fake link
     "https://doi.org",  # These don't resolve properly and cause SSL issues
+    "https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html",  # anchors throw a 403 forbidden error
+    "https://docutils.sourceforge.io/docs/ref/rst/directives.html",  # anchors throw a 403 forbidden error
 ]
 linkcheck_exclude_documents = ["changelog"]
 

docs/contributing/tests.md

@@ -14,8 +14,8 @@ $ tox
 You can specify a specific environment like so:
 
 ```console
-# Run the tests with Python 3.10, Sphinx 6
-$ tox -e py310-sphinx6
+# Run the tests with Python 3.12, Sphinx 8
+$ tox -e py312-sphinx8
 ```
 
 ## List all test environments
@@ -46,7 +46,7 @@ By default, `tox` will only install the necessary environment **once**.
 If you'd like to force a re-build, use the `-r` parameter. For example:
 
 ```console
-$ tox -r -e py310-sphinx6
+$ tox -r -e py312-sphinx8
 ```
 
 ## Test audits with lighthouse
@@ -63,7 +63,7 @@ To preview the output of these tests:
 
 ## Test multiple Sphinx versions
 
-This theme is tested against Sphinx 6-9.
+This theme is tested against Sphinx 7-9.
 We try to set up our regression tests such that there are no differences between these Sphinx versions.
 
 ### Unit tests

pyproject.toml

@@ -27,6 +27,8 @@ filterwarnings = [
   '''ignore:'sphinx.util.import_object' is deprecated.:PendingDeprecationWarning''',
   'ignore:Parsing dates involving a day of month without a year specified is ambiguious:DeprecationWarning',
   'ignore:Argument "parser_name" will be removed in Docutils 2.0.:PendingDeprecationWarning',
+  # RemovedInSphinx11Warning triggered in sphinx -- ultimately should be fixed
+  "ignore:'sphinx_book_theme._transforms.HandleFootnoteTransform.app' is deprecated.:PendingDeprecationWarning",
 ]
 
 [project]
@@ -35,9 +37,9 @@ description = "A clean book theme for scientific explanations and documentation
 dynamic = ["version"]
 readme = "README.md"
 
-requires-python = ">=3.9"
+requires-python = ">=3.11"
 dependencies = [
-  "sphinx>=6.1",
+  "sphinx>=7.0",
   "pydata-sphinx-theme==0.16.1"
 ]
 
@@ -61,7 +63,7 @@ code_style = [
     "pre-commit"
 ]
 doc = [
-    "ablog",
+    "ablog>=0.11.13",
     "ipywidgets",
     "folium",
     "numpy",

tests/test_build.py

@@ -9,13 +9,8 @@
 import sphinx
 from sphinx.testing.util import SphinxTestApp
 
-sphinx_version = parse(version("sphinx"))
-if sphinx_version.major < 7:
-    from sphinx.testing.path import path as sphinx_path
-else:
-    from pathlib import Path as sphinx_path
-
 
+sphinx_version = parse(version("sphinx"))
 path_tests = Path(__file__).parent
 
 
@@ -56,7 +51,7 @@ def html_tree(self, *path):
 def sphinx_build_factory(make_app, tmp_path):
     def _func(src_folder, **kwargs):
         copytree(path_tests / "sites" / src_folder, tmp_path / src_folder)
-        app = make_app(srcdir=sphinx_path(tmp_path / src_folder), **kwargs)
+        app = make_app(srcdir=Path(tmp_path / src_folder), **kwargs)
         return SphinxBuild(app, tmp_path / src_folder)
 
     yield _func
@@ -469,7 +464,7 @@ def test_sidenote(sphinx_build_factory, file_regression):
     page2 = sphinx_build.html_tree("page2.html")
 
     sidenote_html = page2.select("section > #sidenotes")
-    regression_file = "test_sidenote_6" if sphinx_version.major < 7 else "test_sidenote"
+    regression_file = "test_sidenote"
     file_regression.check(
         sidenote_html[0].prettify(),
         extension=".html",
@@ -487,9 +482,8 @@ def test_marginnote(sphinx_build_factory, file_regression):
     page2 = sphinx_build.html_tree("page2.html")
 
     marginnote_html = page2.select("section > #marginnotes")
-    regression_file = (
-        "test_marginnote_6" if sphinx_version.major < 7 else "test_marginnote"
-    )
+    regression_file = "test_marginnote"
+
     file_regression.check(
         marginnote_html[0].prettify(),
         extension=".html",

tox.ini

@@ -17,7 +17,7 @@ envlist = py313-sphinx8
 usedevelop=true
 passenv = TERM  # To make terminal coloring / other variables pass through
 
-[testenv:py{311,312,313}-pre-commit]
+[testenv:py{311,312,313,314}-pre-commit]
 extras = code_style
 commands = pre-commit run {posargs}
 
@@ -60,9 +60,10 @@ commands =
         --re-ignore ".*\.pyc" \
         --re-ignore ".*~"
 
-[testenv:py{311,312,313}-sphinx{7,8}]
+[testenv:py{311,312,313,314}-sphinx{7,8,9}]
 extras = test
 deps =
     sphinx7: sphinx>=7,<8
     sphinx8: sphinx>=8,<9
+    sphinx9: sphinx>=9,<10
 commands = pytest {posargs}