Merge branch 'master' into master

.github/workflows/publish.yml

@@ -28,7 +28,7 @@ jobs:
           python -m build
 
       - name: Publish
-        uses: pypa/gh-action-pypi-publish@v1.8.11
+        uses: pypa/gh-action-pypi-publish@v1.8.14
         with:
           user: __token__
           password: ${{ secrets.PYPI_KEY }}

.github/workflows/tests.yml

@@ -20,7 +20,7 @@ jobs:
     - uses: actions/setup-python@v5
       with:
         python-version: 3.11
-    - uses: pre-commit/action@v3.0.0
+    - uses: pre-commit/action@v3.0.1
 
   tests:
     continue-on-error: ${{ matrix.experimental || false }}

CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## v1.1.2 -- 2024-02-13
+
+([full changelog](https://github.com/executablebooks/sphinx-book-theme/compare/v1.1.1...3da24da74f6042599fe6c9e2d612f5cbdef42280))
+
+### Enhancements made
+
+- ENH: bump version [#818](https://github.com/executablebooks/sphinx-book-theme/pull/818) ([@agoose77](https://github.com/agoose77))
+
+### Bugs fixed
+
+- FIX: correct event-handler signature [#817](https://github.com/executablebooks/sphinx-book-theme/pull/817) ([@agoose77](https://github.com/agoose77))
+
+### Contributors to this release
+
+([GitHub contributors page for this release](https://github.com/executablebooks/sphinx-book-theme/graphs/contributors?from=2024-02-13&to=2024-02-13&type=c))
+
+[@agoose77](https://github.com/search?q=repo%3Aexecutablebooks%2Fsphinx-book-theme+involves%3Aagoose77+updated%3A2024-02-13..2024-02-13&type=Issues)
+
+## v1.1.1 -- 2024-02-13
+
+([full changelog](https://github.com/executablebooks/sphinx-book-theme/compare/v1.1.0...9335ab99b0bc77b826cb2c5afcef3432f14e8780))
+
+### Enhancements made
+
+- ENH: bump version for 1.1.1 [#815](https://github.com/executablebooks/sphinx-book-theme/pull/815) ([@agoose77](https://github.com/agoose77))
+
+### Bugs fixed
+
+- FIX: use `config-inited` event to register config [#814](https://github.com/executablebooks/sphinx-book-theme/pull/814) ([@agoose77](https://github.com/agoose77))
+
+### Other merged PRs
+
+- Build(deps): Bump actions/setup-python from 4 to 5 [#803](https://github.com/executablebooks/sphinx-book-theme/pull/803) ([@dependabot](https://github.com/dependabot))
+- [pre-commit.ci] pre-commit autoupdate [#801](https://github.com/executablebooks/sphinx-book-theme/pull/801) ([@pre-commit-ci](https://github.com/pre-commit-ci))
+
+### Contributors to this release
+
+([GitHub contributors page for this release](https://github.com/executablebooks/sphinx-book-theme/graphs/contributors?from=2023-12-19&to=2024-02-13&type=c))
+
+[@agoose77](https://github.com/search?q=repo%3Aexecutablebooks%2Fsphinx-book-theme+involves%3Aagoose77+updated%3A2023-12-19..2024-02-13&type=Issues) | [@choldgraf](https://github.com/search?q=repo%3Aexecutablebooks%2Fsphinx-book-theme+involves%3Acholdgraf+updated%3A2023-12-19..2024-02-13&type=Issues) | [@dependabot](https://github.com/search?q=repo%3Aexecutablebooks%2Fsphinx-book-theme+involves%3Adependabot+updated%3A2023-12-19..2024-02-13&type=Issues) | [@ghisvail](https://github.com/search?q=repo%3Aexecutablebooks%2Fsphinx-book-theme+involves%3Aghisvail+updated%3A2023-12-19..2024-02-13&type=Issues) | [@pre-commit-ci](https://github.com/search?q=repo%3Aexecutablebooks%2Fsphinx-book-theme+involves%3Apre-commit-ci+updated%3A2023-12-19..2024-02-13&type=Issues) | [@welcome](https://github.com/search?q=repo%3Aexecutablebooks%2Fsphinx-book-theme+involves%3Awelcome+updated%3A2023-12-19..2024-02-13&type=Issues)
+
+
 ## v1.1.0 -- 2023-12-19
 
 ([full changelog](https://github.com/executablebooks/sphinx-book-theme/compare/v1.0.1...v1.1.0))

docs/sections/sidebar-primary.md

@@ -31,10 +31,11 @@ See the [Sphinx HTML sidebars documentation](https://www.sphinx-doc.org/en/maste
 
 ### Default sidebar elements
 
-By default, this theme comes with these three theme-specific sidebar elements enabled on all pages:
+By default, this theme comes with these theme-specific sidebar elements enabled on all pages:
 
 - `navbar-logo.html`: Displays the logo and site title.
-- `search-field.html`: A bootstrap-based search bar (from the [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/))
+- `icon-links.html`: Displays [icon links](icon-links)
+- `search-button-field.html`: A bootstrap-based search bar (from the [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/))
 - `sbt-sidebar-nav.html`: A bootstrap-based navigation menu for your book.
 
 ## Add a header to your Table of Contents

pyproject.toml

@@ -13,6 +13,18 @@ additional-compiled-static-assets = [
 testpaths = [
     "tests"
 ]
+filterwarnings = [
+  "error",
+  'ignore:Jupyter is migrating its paths to use standard platformdirs:DeprecationWarning',
+  'ignore:The frontend\.OptionParser class will be replaced:DeprecationWarning',
+  'ignore:The frontend\.Option class will be removed:DeprecationWarning',
+  'ignore:nodes\.Node\.traverse\(\) is obsoleted by Node\.findall\(\):PendingDeprecationWarning',
+  # jupyter-client throws this
+  'ignore:datetime\.datetime\.utcfromtimestamp\(\) is deprecated:DeprecationWarning',
+  'ignore:datetime\.datetime\.utcnow\(\) is deprecated:DeprecationWarning',
+  # Sphinx triggers this
+  '''ignore:'imghdr' is deprecated and slated for removal in Python 3\.13:DeprecationWarning''',
+]
 
 [project]
 name = "sphinx-book-theme"

src/sphinx_book_theme/__init__.py

@@ -4,13 +4,13 @@
 from pathlib import Path
 from functools import lru_cache
 
-from docutils.parsers.rst.directives.body import Sidebar
 from docutils import nodes as docutil_nodes
 from sphinx.application import Sphinx
 from sphinx.locale import get_translation
 from sphinx.util import logging
 from pydata_sphinx_theme.utils import get_theme_options_dict
 
+from .directives import Margin
 from .nodes import SideNoteNode
 from .header_buttons import (
     prep_header_buttons,
@@ -20,9 +20,10 @@
 )
 from .header_buttons.launch import add_launch_buttons
 from .header_buttons.source import add_source_buttons
+from ._compat import findall
 from ._transforms import HandleFootnoteTransform
 
-__version__ = "1.1.0"
+__version__ = "1.1.2"
 """sphinx-book-theme version"""
 
 SPHINX_LOGGER = logging.getLogger(__name__)
@@ -53,7 +54,7 @@ def add_metadata_to_page(app, pagename, templatename, context, doctree):
     # Add a shortened page text to the context using the sections text
     if doctree:
         description = ""
-        for section in doctree.traverse(docutil_nodes.section):
+        for section in findall(doctree, docutil_nodes.section):
             description += section.astext().replace("\n", " ")
         description = description[:160]
         context["page_description"] = description
@@ -179,33 +180,10 @@ def check_deprecation_keys(app):
             )
 
 
-class Margin(Sidebar):
-    """Goes in the margin to the right of the page."""
-
-    optional_arguments = 1
-    required_arguments = 0
-
-    def run(self):
-        """Run the directive."""
-        if not self.arguments:
-            self.arguments = [""]
-        nodes = super().run()
-        nodes[0].attributes["classes"].append("margin")
-
-        # Remove the "title" node if it is empty
-        if not self.arguments:
-            nodes[0].children.pop(0)
-        return nodes
-
-
-def update_general_config(app):
+def update_general_config(app, config):
     theme_dir = get_html_theme_path()
-    # Update templates for sidebar. Needed for jupyter-book builds as jb
-    # uses an instance of Sphinx class from sphinx.application to build the app.
-    # The __init__ function of which calls self.config.init_values() just
-    # before emitting `config-inited` event. The init_values function overwrites
-    # templates_path variable.
-    app.config.templates_path.append(os.path.join(theme_dir, "components"))
+
+    config.templates_path.append(os.path.join(theme_dir, "components"))
 
 
 def update_templates(app, pagename, templatename, context, doctree):
@@ -245,11 +223,20 @@ def setup(app: Sphinx):
     app.connect("builder-inited", check_deprecation_keys)
     app.connect("builder-inited", update_sourcename)
     app.connect("builder-inited", update_context_with_repository_info)
-    app.connect("builder-inited", update_general_config)
     app.connect("html-page-context", add_metadata_to_page)
     app.connect("html-page-context", hash_html_assets)
     app.connect("html-page-context", update_templates)
 
+    # This extension has both theme-like and extension-like features.
+    # Themes are initialised immediately before use, thus we cannot
+    # rely on an event to set the config - the theme config must be
+    # set in setup(app):
+    update_general_config(app, app.config)
+    # Meanwhile, extensions are initialised _first_, and any config
+    # values set during setup() will be overwritten. We must therefore
+    # register the `config-inited` event to set these config options
+    app.connect("config-inited", update_general_config)
+
     # Nodes
     SideNoteNode.add_node(app)
 
@@ -266,10 +253,6 @@ def setup(app: Sphinx):
     # Post-transforms
     app.add_post_transform(HandleFootnoteTransform)
 
-    # Update templates for sidebar, for builds where config-inited is not called
-    # (does not work in case of jupyter-book)
-    app.config.templates_path.append(os.path.join(theme_dir, "components"))
-
     return {
         "parallel_read_safe": True,
         "parallel_write_safe": True,

src/sphinx_book_theme/_compat.py

@@ -0,0 +1,9 @@
+from docutils.nodes import Element
+from typing import Iterator
+
+
+def findall(node: Element, *args, **kwargs) -> Iterator[Element]:
+    # findall replaces traverse in docutils v0.18
+    # note a difference is that findall is an iterator
+    impl = getattr(node, "findall", node.traverse)
+    return iter(impl(*args, **kwargs))

src/sphinx_book_theme/_transforms.py

@@ -4,6 +4,7 @@
 from sphinx import addnodes as sphinx_nodes
 from pydata_sphinx_theme.utils import get_theme_options_dict
 from .nodes import SideNoteNode
+from ._compat import findall
 
 
 class HandleFootnoteTransform(SphinxPostTransform):
@@ -19,10 +20,10 @@ def run(self, **kwargs: Any) -> None:
         # Cycle through footnote references, and move their content next to the
         # reference. This lets us display the reference in the margin,
         # or just below on narrow screens.
-        for ref_node in self.document.traverse(docutil_nodes.footnote_reference):
+        for ref_node in findall(self.document, docutil_nodes.footnote_reference):
             parent = None
             # Each footnote reference should have a single node it points to via `ids`
-            for foot_node in self.document.traverse(docutil_nodes.footnote):
+            for foot_node in findall(self.document, docutil_nodes.footnote):
                 # matching the footnote reference with footnote
                 if (
                     len(foot_node.attributes["backrefs"])

src/sphinx_book_theme/assets/styles/sections/_header-article.scss

@@ -91,7 +91,8 @@ label.sidebar-toggle.secondary-toggle {
     font-size: 1.3rem;
     color: var(--pst-color-text-muted);
     border: none;
-    padding: 0 0.5rem;
+    padding-left: 0.5rem;
+    padding-right: 0.5rem;
 
     // Make sure anything inside is aligned vertically
     display: flex;

src/sphinx_book_theme/directives.py

@@ -0,0 +1,20 @@
+from docutils.parsers.rst.directives.body import Sidebar
+
+
+class Margin(Sidebar):
+    """Goes in the margin to the right of the page."""
+
+    optional_arguments = 1
+    required_arguments = 0
+
+    def run(self):
+        """Run the directive."""
+        if not self.arguments:
+            self.arguments = [""]
+        nodes = super().run()
+        nodes[0].attributes["classes"].append("margin")
+
+        # Remove the "title" node if it is empty
+        if not self.arguments:
+            nodes[0].children.pop(0)
+        return nodes

src/sphinx_book_theme/header_buttons/launch.py

@@ -1,4 +1,5 @@
 """Launch buttons for Binder / Thebe / Colab / etc."""
+
 from pathlib import Path
 from typing import Any, Dict, Optional
 from urllib.parse import urlencode, quote
@@ -133,7 +134,7 @@ def add_launch_buttons(
             {
                 "type": "link",
                 "text": "Binder",
-                "tooltip": translation("Launch on") + "Binder",
+                "tooltip": translation("Launch on") + " Binder",
                 "icon": "_static/images/logo_binder.svg",
                 "url": url,
             }
@@ -151,7 +152,7 @@ def add_launch_buttons(
             {
                 "type": "link",
                 "text": "JupyterHub",
-                "tooltip": translation("Launch on") + "JupyterHub",
+                "tooltip": translation("Launch on") + " JupyterHub",
                 "icon": "_static/images/logo_jupyterhub.svg",
                 "url": url,
             }
@@ -166,7 +167,7 @@ def add_launch_buttons(
                 {
                     "type": "link",
                     "text": "Colab",
-                    "tooltip": translation("Launch on") + "Colab",
+                    "tooltip": translation("Launch on") + " Colab",
                     "icon": "_static/images/logo_colab.png",
                     "url": url,
                 }
@@ -182,7 +183,7 @@ def add_launch_buttons(
                 {
                     "type": "link",
                     "text": "Deepnote",
-                    "tooltip": translation("Launch on") + "Deepnote",
+                    "tooltip": translation("Launch on") + " Deepnote",
                     "icon": "_static/images/logo_deepnote.svg",
                     "url": url,
                 }

src/sphinx_book_theme/theme/sphinx_book_theme/macros/buttons.html

@@ -6,7 +6,7 @@
   {% if icon.startswith("fa") -%}
     <i class="{{ icon }}"></i>
   {% else %}
-    <img src="{{ pathto(icon, 1) }}">
+    <img alt="{{ translate(text) }} {{ translate("logo") }}" src="{{ pathto(icon, 1) }}">
   {% endif -%}
 </span>
 {% endif %}

tests/test_build.py

@@ -1,7 +1,6 @@
 import os
 from pathlib import Path
 from shutil import copytree, rmtree
-from subprocess import check_call
 from importlib.metadata import version
 from packaging.version import parse
 
@@ -28,9 +27,10 @@ def __init__(self, app: SphinxTestApp, src: Path):
             f".sphinx{sphinx.version_info[0]}"  # software version tracking for fixtures
         )
 
-    def build(self, assert_pass=True):
+    def build(self, assert_pass=True, assert_no_warnings=True):
         self.app.build()
-        assert self.warnings == "", self.status
+        if assert_no_warnings:
+            assert self.warnings == "", self.status
         return self
 
     @property
@@ -62,14 +62,12 @@ def _func(src_folder, **kwargs):
     yield _func
 
 
-def test_parallel_build():
-    # We cannot use the sphinx_build_factory because SpinxTestApp does
-    # 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(
-        f"sphinx-build -j 2 -W -b html {path_tests}/sites/parallel-build build",
-        shell=True,
-    )
+def test_parallel_build(sphinx_build_factory):
+    sphinx_build = sphinx_build_factory("parallel-build", parallel=2)  # type: SphinxBuild
+    sphinx_build.build(
+        assert_pass=True, assert_no_warnings=False
+    )  # TODO: filter these warnings
+    assert (sphinx_build.outdir / "index.html").exists(), sphinx_build.outdir.glob("*")
 
 
 def test_build_book(sphinx_build_factory, file_regression):