Sphinx 7 support

.github/workflows/tests.yml

@@ -23,36 +23,38 @@ jobs:
     - uses: pre-commit/[email protected]
 
   tests:
+    continue-on-error: ${{ matrix.experimental || false }}
     strategy:
+      fail-fast: false
       matrix:
         os: [ubuntu-latest]
         python-version: ["3.9", "3.10", "3.11"]
         # Only test the latest major release of Sphinx because otherwise we need to
         # keep multiple versions of regression tests on file and this creates lots of
         # noise in the tests.
-        sphinx: [">=6,<7"]
+        sphinx: ["~=5.0","~=6.0","~=7.0"]
         include:
         - os: windows-latest
-          python-version: 3.11
-          sphinx: ">=6,<7"
+          python-version: 3.x
+          # Windows pulling in dependencies fails
+          experimental: true
         - os: macos-latest
-          python-version: 3.11
-          sphinx: ">=6,<7"
+          python-version: 3.x
     runs-on: ${{ matrix.os }}
 
     steps:
     - uses: actions/checkout@v4
-    - name: Set up Python ${{ matrix.python-version }} and Sphinx ${{ matrix.sphinx }}
+    - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
         cache: "pip"
         cache-dependency-path: "pyproject.toml"
 
-    - name: Install dependencies
+    - name: Install dependencies with Sphinx ${{ matrix.sphinx }}
       run: |
         python -m pip install --upgrade pip
-        python -m pip install -e .[test]
+        python -m pip install --upgrade "sphinx${{matrix.sphinx}}" -e .[test] --pre
 
     - name: Run pytest
       run: >

pyproject.toml

@@ -22,7 +22,7 @@ readme = "README.md"
 
 requires-python = ">=3.9"
 dependencies = [
-  "sphinx>=4,<7",
+  "sphinx>=5",
   "pydata-sphinx-theme>=0.14",
 ]
 

tests/sites/base/conf.py

@@ -30,4 +30,5 @@
         "notebook_interface": "jupyterlab",
         "thebe": True,
     },
+    "navigation_with_keys": True,
 }

tests/sites/notitle/conf.py

@@ -11,4 +11,5 @@
 
 html_theme_options = {
     "home_page_in_toc": True,
+    "navigation_with_keys": True,
 }

tests/sites/parallel-build/conf.py

@@ -3,3 +3,6 @@
 """
 
 html_theme = "sphinx_book_theme"
+html_theme_options = {
+    "navigation_with_keys": True,
+}

tests/test_build.py

@@ -2,12 +2,19 @@
 from pathlib import Path
 from shutil import copytree, rmtree
 from subprocess import check_call
+from importlib.metadata import version
+from packaging.version import parse
 
 from bs4 import BeautifulSoup
 import pytest
 import sphinx
 from sphinx.testing.util import SphinxTestApp
-from sphinx.testing.path import path as sphinx_path
+
+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
 
 
 path_tests = Path(__file__).parent
@@ -49,9 +56,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(os.path.abspath((tmp_path / src_folder))), **kwargs
-        )
+        app = make_app(srcdir=sphinx_path(tmp_path / src_folder), **kwargs)
         return SphinxBuild(app, tmp_path / src_folder)
 
     yield _func
@@ -62,7 +67,8 @@ def test_parallel_build():
     # not have a way to pass parallel=2 to the Sphinx constructor
     # https://github.com/sphinx-doc/sphinx/blob/d8c006f1c0e612d0dc595ae463b8e4c3ebee5ca4/sphinx/testing/util.py#L101
     check_call(
-        "sphinx-build -j 2 -W -b html tests/sites/parallel-build build", shell=True
+        f"sphinx-build -j 2 -W -b html {path_tests}/sites/parallel-build build",
+        shell=True,
     )
 
 
@@ -187,6 +193,7 @@ def test_header_repository_buttons(
             "use_repository_button": repo,
             "use_issues_button": issues,
             "repository_url": "https://github.com/executablebooks/sphinx-book-theme",
+            "navigation_with_keys": True,
         }
     }
     sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build(
@@ -225,6 +232,7 @@ def test_source_button_url(sphinx_build_factory, file_regression, provider, repo
             "use_edit_page_button": True,
             "use_source_button": True,
             "use_issues_button": use_issues,
+            "navigation_with_keys": True,
         }
     }
     # Decide if we've manually given the provider
@@ -278,7 +286,10 @@ def test_empty_header_launchbtns(sphinx_build_factory, file_regression):
     sphinx_build = sphinx_build_factory(
         "base",
         confoverrides={
-            "html_theme_options": {"launch_buttons": {"notebook_interface": "notebook"}}
+            "html_theme_options": {
+                "launch_buttons": {"notebook_interface": "notebook"},
+                "navigation_with_keys": True,
+            }
         },
     ).build(assert_pass=True)
     launch_btns = sphinx_build.html_tree("section1", "ntbk.html").select(
@@ -313,6 +324,7 @@ def test_launch_button_url(sphinx_build_factory, file_regression, provider, repo
             "repository_branch": "foo",
             "path_to_docs": "docs",
             "launch_buttons": launch_buttons,
+            "navigation_with_keys": True,
         }
     }
 
@@ -352,6 +364,7 @@ def test_repo_custombranch(sphinx_build_factory, file_regression):
                 "use_edit_page_button": True,
                 "repository_url": "https://github.com/executablebooks/sphinx-book-theme",  # noqa: E501
                 "launch_buttons": {"binderhub_url": "https://mybinder.org"},
+                "navigation_with_keys": True,
             }
         },
     ).build(assert_pass=True)
@@ -388,7 +401,12 @@ def test_show_navbar_depth(sphinx_build_factory):
     """Test with different levels of show_navbar_depth."""
     sphinx_build = sphinx_build_factory(
         "base",
-        confoverrides={"html_theme_options.show_navbar_depth": 2},
+        confoverrides={
+            "html_theme_options": {
+                "show_navbar_depth": 2,
+                "navigation_with_keys": True,
+            }
+        },
     ).build(
         assert_pass=True
     )  # type: SphinxBuild
@@ -404,7 +422,10 @@ def test_show_navbar_depth(sphinx_build_factory):
 def test_header_download_button_off(sphinx_build_factory):
     """Download button should not show up in the header when configured as False."""
     confoverrides = {
-        "html_theme_options.use_download_button": False,
+        "html_theme_options": {
+            "use_download_button": False,
+            "navigation_with_keys": True,
+        }
     }
     sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build(
         assert_pass=True
@@ -456,8 +477,12 @@ 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"
     file_regression.check(
-        sidenote_html[0].prettify(), extension=".html", encoding="utf8"
+        sidenote_html[0].prettify(),
+        extension=".html",
+        encoding="utf8",
+        basename=regression_file,
     )
 
 
@@ -470,6 +495,12 @@ 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"
+    )
     file_regression.check(
-        marginnote_html[0].prettify(), extension=".html", encoding="utf8"
+        marginnote_html[0].prettify(),
+        extension=".html",
+        encoding="utf8",
+        basename=regression_file,
     )

tests/test_build/test_marginnote.html

@@ -4,7 +4,7 @@ <h2>
    2.2.
   </span>
   Marginnotes
-  <a class="headerlink" href="#marginnotes" title="Permalink to this heading">
+  <a class="headerlink" href="#marginnotes" title="Link to this heading">
    #
   </a>
  </h2>

tests/test_build/test_marginnote_6.html

@@ -0,0 +1,38 @@
+<section id="marginnotes">
+ <h2>
+  <span class="section-number">
+   2.2.
+  </span>
+  Marginnotes
+  <a class="headerlink" href="#marginnotes" title="Permalink to this heading">
+   #
+  </a>
+ </h2>
+ <p>
+  Some text to test out one marginnote
+  <label class="margin-toggle marginnote-label" for="marginnote-role-2">
+  </label>
+  <input class="margin-toggle" id="marginnote-role-2" name="marginnote-role-2" type="checkbox"/>
+  <span class="marginnote">
+   This is a marginnote.
+  </span>
+  and another marginnote
+  <label class="margin-toggle marginnote-label" for="marginnote-role-6">
+  </label>
+  <input class="margin-toggle" id="marginnote-role-6" name="marginnote-role-6" type="checkbox"/>
+  <span class="marginnote">
+   This is
+   <em>
+    another
+   </em>
+   <strong>
+    marginnote
+   </strong>
+   .
+  </span>
+ </p>
+ <p>
+  This is the end of Page 2.
+ </p>
+ <hr class="footnotes docutils"/>
+</section>

tests/test_build/test_sidenote.html

@@ -4,7 +4,7 @@ <h2>
    2.1.
   </span>
   Sidenotes
-  <a class="headerlink" href="#sidenotes" title="Permalink to this heading">
+  <a class="headerlink" href="#sidenotes" title="Link to this heading">
    #
   </a>
  </h2>

tests/test_build/test_sidenote_6.html

@@ -0,0 +1,50 @@
+<section id="sidenotes">
+ <h2>
+  <span class="section-number">
+   2.1.
+  </span>
+  Sidenotes
+  <a class="headerlink" href="#sidenotes" title="Permalink to this heading">
+   #
+  </a>
+ </h2>
+ <p>
+  Some text to test out one sidenote
+  <label class="margin-toggle" for="sidenote-role-1">
+   <span id="id1">
+    <sup>
+     1
+    </sup>
+   </span>
+  </label>
+  <input class="margin-toggle" id="sidenote-role-1" name="sidenote-role-1" type="checkbox"/>
+  <span class="sidenote">
+   <sup>
+    1
+   </sup>
+   This is a sidenote.
+  </span>
+  and another sidenote
+  <label class="margin-toggle" for="sidenote-role-3">
+   <span id="id2">
+    <sup>
+     3
+    </sup>
+   </span>
+  </label>
+  <input class="margin-toggle" id="sidenote-role-3" name="sidenote-role-3" type="checkbox"/>
+  <span class="sidenote">
+   <sup>
+    3
+   </sup>
+   This is
+   <em>
+    another
+   </em>
+   <strong>
+    sidenote
+   </strong>
+   .
+  </span>
+ </p>
+</section>