sunpy-sphinx-theme 2.3.0__tar.gz → 2.4.0__tar.gz

{sunpy_sphinx_theme-2.3.0 → sunpy_sphinx_theme-2.4.0}/.rtd-environment.yml

@@ -2,6 +2,6 @@ name: rtd_sunpy_sphinx_theme
 channels:
   - conda-forge
 dependencies:
-  - python=3.11
+  - python=3.14
   - pip
   - graphviz!=2.42.*,!=2.43.*

{sunpy_sphinx_theme-2.3.0 → sunpy_sphinx_theme-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sunpy-sphinx-theme
-Version: 2.3.0
+Version: 2.4.0
 Summary: The sphinx theme for the SunPy website and documentation.
 Author: The SunPy Developers
 License: BSD 2-Clause License
@@ -36,10 +36,10 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Framework :: Sphinx
 Classifier: Framework :: Sphinx :: Theme
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.9
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE.md
-Requires-Dist: pydata-sphinx-theme<0.23,>=0.22.0rc0
+Requires-Dist: pydata-sphinx-theme<0.24,>=0.22.0
 Requires-Dist: sphinxext-opengraph>=0.13
 Requires-Dist: sphinx>=7.3.0
 Provides-Extra: docs
@@ -50,6 +50,9 @@ Requires-Dist: sphinx-design; extra == "docs"
 Requires-Dist: sphinx-gallery; extra == "docs"
 Requires-Dist: sphinx-togglebutton; extra == "docs"
 Requires-Dist: sunpy; extra == "docs"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-playwright; extra == "test"
 Dynamic: license-file
 
 # SunPy Project Sphinx Theme

sunpy_sphinx_theme-2.4.0/conftest.py

@@ -0,0 +1,142 @@
+"""Configuration of the pytest session."""
+
+from __future__ import annotations
+
+import sys
+import time
+from http.client import HTTPConnection
+from os import environ
+from pathlib import Path
+from shutil import copytree
+from subprocess import PIPE, Popen
+from typing import TYPE_CHECKING
+
+import pytest
+from bs4 import BeautifulSoup
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from sphinx.testing.util import SphinxTestApp
+
+pytest_plugins = "sphinx.testing.fixtures"
+
+repo_path = Path(__file__).parent
+tests_path = repo_path / "src" / "sunpy_sphinx_theme" / "tests"
+docs_build_path = repo_path / "docs" / "_build" / "html"
+
+
+# -- global fixture to build sphinx tmp docs ---------------------------------
+
+
+class SphinxBuild:
+    """Helper class to build a test documentation."""
+
+    def __init__(self, app: SphinxTestApp, src: Path):
+        self.app = app
+        self.src = src
+
+    def build(self, *, no_warning: bool = True) -> SphinxBuild:
+        """Build the application."""
+        self.app.build()
+        if no_warning is True:
+            assert self.warnings == "", self.status
+        return self
+
+    @property
+    def status(self) -> str:
+        """Returns the status of the current build."""
+        return self.app.status.getvalue()
+
+    @property
+    def warnings(self) -> str:
+        """Returns the warnings raised by the current build."""
+        return self.app.warning.getvalue()
+
+    @property
+    def outdir(self) -> Path:
+        """Returns the output directory of the current build."""
+        return Path(self.app.outdir)
+
+    def html_tree(self, *path) -> BeautifulSoup:
+        """Returns the html tree of the current build."""
+        path_page = self.outdir.joinpath(*path)
+        if not path_page.exists():
+            msg = f"{path_page} does not exist"
+            raise ValueError(msg)
+        return BeautifulSoup(path_page.read_text("utf8"), "html.parser")
+
+
+@pytest.fixture
+def sphinx_build_factory(make_app: Callable, tmp_path: Path, request) -> Callable:
+    """Return a factory builder pointing to the tmp directory."""
+
+    def _func(src_folder: str, files: dict[str, str] | None = None, **kwargs) -> SphinxBuild:
+        """Create the SphinxBuild from the source folder."""
+        no_temp = environ.get("SST_TEST_HTML_DIR")
+        nonlocal tmp_path
+        if no_temp is not None:
+            tmp_path = Path(no_temp) / request.node.name / str(src_folder)
+        srcdir = tmp_path / src_folder
+        copytree(tests_path / "sites" / src_folder, tmp_path / src_folder)
+        for filename, contents in (files or {}).items():
+            filepath = Path(srcdir / filename).resolve()
+            filepath.parent.mkdir(exist_ok=True, parents=True)
+            filepath.write_text(contents)
+        app = make_app(srcdir=srcdir, **kwargs)
+        return SphinxBuild(app, tmp_path / src_folder)
+
+    return _func
+
+
+# -- global fixture to serve the built docs ----------------------------------
+
+
+@pytest.fixture(scope="module")
+def url_base():
+    """Start local server on built docs and return the localhost URL as the base URL."""
+    # The accessibility tests are run against a build of our documentation, so
+    # fail early with a helpful message if it has not been built yet.
+    if not docs_build_path.is_dir():
+        msg = f"No docs build found at {docs_build_path}; build it first with 'tox -e build_docs'"
+        pytest.fail(msg, pytrace=False)
+
+    # Use a port that is not commonly used during development or else you will
+    # force the developer to stop running their dev server in order to run the
+    # tests.
+    port = 8213
+    host = "localhost"
+    url = f"http://{host}:{port}"
+
+    # Try starting the server
+    process = Popen(
+        [sys.executable, "-m", "http.server", str(port), "--directory", docs_build_path],
+        stdout=PIPE,
+    )
+
+    # Try connecting to the server
+    retries = 5
+    while retries > 0:
+        conn = HTTPConnection(host, port)
+        try:
+            conn.request("HEAD", "/")
+            response = conn.getresponse()
+            if response is not None:
+                yield url
+                break
+        except ConnectionRefusedError:
+            time.sleep(1)
+            retries -= 1
+        finally:
+            conn.close()
+
+    # If the code above never yields a URL, then we were never able to connect
+    # to the server and retries == 0.
+    if not retries:
+        msg_0 = "Failed to start http server in 5 seconds"
+        raise RuntimeError(msg_0)
+    else:
+        # Otherwise the server started and this fixture is done now and we clean
+        # up by stopping the server.
+        process.terminate()
+        process.wait()

sunpy_sphinx_theme-2.4.0/flake.nix

@@ -0,0 +1,34 @@
+{
+  description = "A very basic flake";
+
+  inputs = {
+    flake-parts.url = "github:hercules-ci/flake-parts";
+    nixpkgs.url = "github:nixos/nixpkgs";
+  };
+
+  outputs = { flake-parts, ... } @ inputs: flake-parts.lib.mkFlake { inherit inputs; } {
+    perSystem = { config, self', inputs', pkgs, system, ... }: {
+      devShells.default = pkgs.mkShell {
+        # venvShellHook needs venvDir set on the shell
+        venvDir = ".venv";
+
+        packages = with pkgs; [
+          nodejs_latest
+          playwright-driver.browsers
+          uv
+        ];
+
+        # runs every time you enter the shell, after activation
+        shellHook = ''
+          export PLAYWRIGHT_BROWSERS_PATH=${pkgs.playwright-driver.browsers}
+          export PLAYWRIGHT_SKIP_VALIDATE_HOST_REQUIREMENTS=true;
+          uv sync --all-extras
+          source .venv/bin/activate
+          npm install
+        '';
+      };
+    };
+    # Declared systems that your flake supports. These will be enumerated in perSystem
+    systems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
+  };
+}

sunpy_sphinx_theme-2.4.0/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "sunpy-sphinx-theme",
+  "private": true,
+  "description": "Node dependencies for testing the sunpy-sphinx-theme",
+  "devDependencies": {
+    "axe-core": "^4.13.0"
+  }
+}

{sunpy_sphinx_theme-2.3.0 → sunpy_sphinx_theme-2.4.0}/pyproject.toml

@@ -20,9 +20,9 @@ classifiers = [
   "Framework :: Sphinx :: Theme",
   "Operating System :: OS Independent",
 ]
-requires-python = ">=3.9"
+requires-python = ">=3.11"
 dependencies = [
-  "pydata-sphinx-theme>=0.22.0rc0,<0.23",
+  "pydata-sphinx-theme>=0.22.0,<0.24",
   "sphinxext-opengraph>=0.13",
   "sphinx>=7.3.0"
 ]
@@ -37,6 +37,10 @@ docs = [
   "sphinx-togglebutton",
   "sunpy",
 ]
+test = [
+  "pytest>=7.0",
+  "pytest-playwright",
+]
 
 [project.entry-points]
 "sphinx.html_themes" = { sunpy = "sunpy_sphinx_theme" }
@@ -46,6 +50,11 @@ include-package-data = true
 
 [tool.setuptools_scm]
 
+[tool.pytest.ini_options]
+markers = "a11y: mark a test as an accessibility test"
+testpaths = ["tests"]
+addopts = "--durations=10"
+
 [ tool.gilesbot ]
   [ tool.gilesbot.circleci_artifacts.giles ]
     enabled = false

{sunpy_sphinx_theme-2.3.0 → sunpy_sphinx_theme-2.4.0}/ruff.toml

@@ -49,17 +49,14 @@ lint.extend-ignore = [
 "setup.py" = [
     "D100", # Missing docstring in public module
 ]
-"test_*.py" = [
+"{src/sunpy_sphinx_theme/tests/*.py,conftest.py,test_*.py}" = [
     "D100", # Missing docstring in public module
     "D103", # Missing docstring in public function
-    "N806", # in function should be lowercase
+    "INP001", # tests are not part of an implicit namespace package
     "S101", # Use of `assert` detected
-]
-"sunpy_soar/version.py" = [
-    "D100", # Missing docstring in public module
-]
-"sunpy_soar/conftest.py" = [
-    "D100", # Missing docstring in public module
+    "S404", # subprocess module is possibly insecure
+    "S603", # subprocess call: check for execution of untrusted input
+    "ARG001", # Unused function argument (kept for interface compatibility)
 ]
 
 [lint.pydocstyle]

{sunpy_sphinx_theme-2.3.0 → sunpy_sphinx_theme-2.4.0}/src/sunpy_sphinx_theme/__init__.py

@@ -12,6 +12,9 @@ from urllib.parse import urljoin, urlparse
 
 from pydata_sphinx_theme import utils
 from sphinx.application import Sphinx
+from sphinx.util import logging
+
+logger = logging.getLogger(__name__)
 
 __all__ = ["ON_RTD", "PNG_ICON", "SVG_ICON", "get_html_theme_path"]
 
@@ -45,7 +48,7 @@ def update_config(app) -> None:
     theme_options = utils.get_theme_options_dict(app)
 
     if theme_options_with_defaults.get("sst_logo") and not isinstance(theme_options_with_defaults["sst_logo"], dict):
-        sst_logo = str(theme_options["sst_logo"])
+        sst_logo = str(theme_options_with_defaults["sst_logo"])
         theme_options["sst_logo"] = {"light": sst_logo, "dark": sst_logo}
 
     theme_options["sst_is_root"] = bool(theme_options_with_defaults.get("sst_is_root", False))
@@ -188,28 +191,43 @@ def generate_search_config(app):
     This function parses the config for the "Documentation" section of the theme config.
     """
     theme_config = get_theme_options(app)
-    search_projects = theme_config.get("rtd_search_projects", None)
+
+    if not theme_config.get("rtd_search", True):
+        return
+
+    # Add project-wide search
+    app.add_css_file("css/rtd_enhanced_search.css")
+    app.add_js_file(
+        "js/rtd_enhanced_search.js",
+        loading_method="async",
+    )
+
+    def filter_doc_links(links):
+        out_links = []
+        for link in links:
+            if isinstance(link[1], list):
+                out_links += filter_doc_links(link[1])
+            elif isinstance(link[1], str) and link[1].startswith("http"):
+                out_links.append({"name": link[0], "link": link[1]})
+            else:
+                err = f"Unable to parse {link} in the nav tree. Try setting search_projects explicitly or fixing navbar_links."
+                raise ValueError(err)
+        return out_links
+
+    search_projects = theme_config.get("rtd_search_projects", []) or []
     if not search_projects:
         navbar_links = theme_config["navbar_links"]
-        doc_links = next(section[1] for section in navbar_links if section[0] == "Documentation")
-
-        def filter_doc_links(links):
-            out_links = []
-            for link in links:
-                if isinstance(link[1], list):
-                    out_links += filter_doc_links(link[1])
-                elif isinstance(link[1], str) and link[1].startswith("http"):
-                    out_links.append({"name": link[0], "link": link[1]})
-                else:
-                    err = f"Unable to parse {link} in the nav tree. Try setting search_projects explicitly or fixing navbar_links."
-                    raise ValueError(err)
-            return out_links
-
-        search_projects = filter_doc_links(doc_links)
+        doc_links = next((section[1] for section in navbar_links if section[0] == "Documentation"), None)
+        if doc_links:
+            search_projects = filter_doc_links(doc_links)
 
     if extra_search_projects := theme_config.get("rtd_extra_search_projects", None):
         search_projects += filter_doc_links(extra_search_projects)
 
+    if not search_projects:
+        logger.info("No RTD search projects were found, disabling RTD search.")
+        return
+
     load_more_label = theme_config.get("rtd_search_load_more_label", "Load more results")
     no_results_label = theme_config.get("rtd_search_no_results_label", "There are no results for this search")
     script = dedent(f"""
@@ -227,30 +245,24 @@ def generate_search_config(app):
     app.add_js_file(None, body=script)
 
 
-def setup(app: Sphinx):
-    app.setup_extension("sphinxext.opengraph")
-
-    # Register theme
-    theme_dir = get_html_theme_path()
-    app.add_html_theme("sunpy", theme_dir)
-    app.add_css_file("sunpy_style.css", priority=600)
-    app.connect("builder-inited", update_config, priority=100)
-    app.connect("builder-inited", generate_search_config, priority=500)
-    app.connect("html-page-context", update_opengraph_context, priority=400)
-    app.connect("html-page-context", update_html_context)
-    # Conditionally include goat counter js
-    # We can't do this in update_config as that causes the scripts to be duplicated.
-    # Also in here none of the theme defaults have be applied by `update_config`
-    # TODO: Improve this mess
-    theme_options = utils.get_theme_options_dict(app)
+def configure_goatcounter(app):
+    """
+    Conditionally include goat counter js and configure endpoint.
+    """
+    theme_options = get_theme_options(app)
     # We want to default to the sunpy goat counter only if the sst_site_root is sunpy.org
     root_domain = theme_options.get("sst_site_root", "https://sunpy.org")
     sunpy_goat_url = "https://sunpy.goatcounter.com/count"
-    default_goat_url = sunpy_goat_url if root_domain == "https://sunpy.org" else None
-    if primary_goat_url := theme_options.get("goatcounter_analytics_url", default_goat_url):
+    default_goat_url = (
+        sunpy_goat_url if root_domain == "https://sunpy.org" else False
+    )  # Only default on sunpy.org pages
+    # The theme default is 'DEFAULT', to allow disabling it
+    primary_goat_url = theme_options.get("goatcounter_analytics_url", "DEFAULT")
+    primary_goat_url = primary_goat_url if primary_goat_url != "DEFAULT" else default_goat_url
+    if primary_goat_url:
         root_domain = root_domain.removeprefix("https://").removeprefix("http://")
         default_endpoint = theme_options.get("goatcounter_non_domain_endpoint", False)
-        if default_endpoint is False:
+        if default_endpoint in (False, "False"):  # sphinx config can sometimes be str
             default_endpoint = ""
         app.add_js_file(
             None,
@@ -270,18 +282,25 @@ def setup(app: Sphinx):
             "https://gc.zgo.at/count.js",
             loading_method="async",
         )
-        app.add_js_file(
-            "js/submenu-concertina-toggle.js",
-            loading_method="async",
-        )
 
-        if theme_options.get("rtd_search", True):
-            # Add project-wide search
-            app.add_css_file("css/rtd_enhanced_search.css")
-            app.add_js_file(
-                "js/rtd_enhanced_search.js",
-                loading_method="async",
-            )
+
+def setup(app: Sphinx):
+    app.setup_extension("sphinxext.opengraph")
+
+    # Register theme
+    theme_dir = get_html_theme_path()
+    app.add_html_theme("sunpy", theme_dir)
+    app.add_css_file("sunpy_style.css", priority=600)
+    app.connect("builder-inited", update_config, priority=100)
+    app.connect("builder-inited", generate_search_config, priority=500)
+    app.connect("builder-inited", configure_goatcounter, priority=510)
+    app.connect("html-page-context", update_opengraph_context, priority=400)
+    app.connect("html-page-context", update_html_context)
+
+    app.add_js_file(
+        "js/submenu-concertina-toggle.js",
+        loading_method="async",
+    )
 
     return {
         "parallel_read_safe": True,

sunpy_sphinx_theme-2.4.0/src/sunpy_sphinx_theme/tests/__init__.py

@@ -0,0 +1,3 @@
+"""
+Tests.
+"""

sunpy_sphinx_theme-2.4.0/src/sunpy_sphinx_theme/tests/helpers.py

@@ -0,0 +1,13 @@
+def inline_scripts(html_tree):
+    """Return the content of all inline scripts in a page."""
+    return [script.string for script in html_tree.select("script") if script.string]
+
+
+def script_srcs(html_tree):
+    """Return the src URLs of all external scripts in a page."""
+    return [script["src"] for script in html_tree.select("script[src]")]
+
+
+def stylesheet_hrefs(html_tree):
+    """Return the hrefs of all stylesheets in a page."""
+    return [link["href"] for link in html_tree.select("link[rel='stylesheet']")]

sunpy_sphinx_theme-2.4.0/src/sunpy_sphinx_theme/tests/sites/base/conf.py

@@ -0,0 +1,9 @@
+"""Test conf file."""
+
+project = "SunPy Theme Tests"
+copyright = "2026, The SunPy Community"  # NOQA: A001
+author = "The SunPy Community"
+
+extensions = []
+html_theme = "sunpy"
+html_static_path = []

sunpy_sphinx_theme-2.4.0/src/sunpy_sphinx_theme/tests/sites/base/index.rst

@@ -0,0 +1,4 @@
+Test Documentation
+==================
+
+A page used to test the theme.

sunpy_sphinx_theme-2.4.0/src/sunpy_sphinx_theme/tests/sites/derived/conf.py

@@ -0,0 +1,16 @@
+"""Test conf file for a theme derived from the sunpy theme."""
+
+from pathlib import Path
+
+project = "SunPy Derived Theme Tests"
+copyright = "2026, The SunPy Community"  # NOQA: A001
+author = "The SunPy Community"
+
+extensions = ["sunpy_sphinx_theme"]
+html_theme = "derived"
+html_static_path = []
+
+
+def setup(app):
+    """Register the derived theme with Sphinx."""
+    app.add_html_theme("derived", str(Path(__file__).parent / "theme"))

sunpy_sphinx_theme-2.4.0/src/sunpy_sphinx_theme/tests/sites/derived/index.rst

@@ -0,0 +1,4 @@
+Test Documentation
+==================
+
+A page used to test a theme derived from the sunpy theme.

sunpy_sphinx_theme-2.4.0/src/sunpy_sphinx_theme/tests/sites/derived/theme/theme.toml

@@ -0,0 +1,15 @@
+[theme]
+inherit = "sunpy"
+
+[options]
+sst_site_root = "https://example.org/"
+navbar_links = [
+    ["Home", "index.html", 2],
+    ["Docs", "https://docs.example.org/", 3],
+]
+footer_links = [
+    ["Footer Example", "https://footer.example.org/", 3],
+]
+rtd_search_projects = [
+    { name = "example", link = "https://example.org/docs/" },
+]

sunpy_sphinx_theme-2.4.0/src/sunpy_sphinx_theme/tests/test_a11y.py

@@ -0,0 +1,177 @@
+"""
+Using Axe-core, scan the documentation pages for accessibility violations.
+Note that in contrast with the rest of our tests, the accessibility tests in this file
+are run against a build of our test documentation, not purposely-built test sites.
+"""
+
+from urllib.parse import urljoin
+
+import pytest
+
+# Using importorskip to ensure these tests are only loaded if Playwright is installed.
+playwright = pytest.importorskip("playwright")
+from playwright.sync_api import Page, expect  # noqa: E402
+
+# Important note: automated accessibility scans can only find a fraction of
+# potential accessibility issues.
+#
+# This test file scans pages from our documentation with a JavaScript library
+# called Axe-core, which checks the page for accessibility violations, such as
+# places on the page with poor color contrast that would be hard for people
+# with low vision to see.
+#
+# Just because a page passes the scan with no accessibility violations does
+# *not* mean that it will be generally usable by a broad range of disabled
+# people. It just means that page is free of common testable accessibility
+# pitfalls.
+
+
+def filter_ignored_violations(violations, url_pathname, theme):
+    """Filter out ignored axe-core violations.
+
+    In some tests, we wish to ignore certain accessibility violations that we
+    won't ever fix or that we don't plan to fix soon.
+    """
+    new_violations = []
+
+    for violation in violations:
+        ignore = False
+
+        # TODO: Our light theme link color does not pass, either fix it or just accept it
+        if violation["id"] == "color-contrast" and theme == "light":
+            ignore = True
+        # This one is probably fine, it's the headings inside the popup
+        if url_pathname == "/cards.html" and violation["id"] == "heading-order":
+            ignore = True
+
+        if url_pathname == "/subsections.html" and violation["id"] in ("region", "summary-name"):
+            ignore = True
+
+        if url_pathname == "/index.html" and violation["id"] in ("region", "summary-name"):
+            ignore = True
+
+        if not ignore:
+            new_violations.append(violation)
+
+    # No violations are currently ignored for our documentation pages. When a
+    # violation is found that we do not plan to fix, filter it out here by
+    # url_pathname and rule id, in the same manner as the pydata-sphinx-theme
+    # does in its tests/test_a11y.py.
+    return new_violations
+
+
+def format_violations(violations):
+    """Return a pretty string representation of Axe-core violations."""
+    result = f"""
+
+        Found {len(violations)} accessibility violation(s):
+        """
+
+    for violation in violations:
+        result += f"""
+
+            - Rule violated:
+              {violation["id"]} - {violation["help"]}
+                - URL: {violation["helpUrl"]}
+                - Impact: {violation["impact"]}
+                - Tags: {" ".join(violation["tags"])}
+                - Targets:"""
+
+        for node in violation["nodes"]:
+            for target in node["target"]:
+                result += f"""
+                    - {target}"""
+
+        result += "\n\n"
+
+    return result
+
+
+@pytest.mark.a11y
+@pytest.mark.parametrize("theme", ["light", "dark"])
+@pytest.mark.parametrize(
+    ("url_pathname", "selector"),
+    [
+        # The Kitchen Sink page of our test documentation
+        ("/colors.html", "#colors"),
+        ("/colors.html", "#admonitions"),
+        ("/colors.html", "#snippets"),
+        # The theme configuration page, including the header and footer
+        # elements it renders (navbar links, footer links, footer center)
+        ("/customizing.html", "#customizing-the-theme"),
+        ("/customizing.html", "#changing-the-theme-settings"),
+        ("/customizing.html", "#adjusting-the-styling"),
+        # The sphinx-design components used by our documentation
+        ("/web-components.html", "#sphinx-design-components"),
+        ("/web-components.html", "#badges-and-button-links"),
+        ("/web-components.html", "#cards"),
+        ("/web-components.html", "#tabs"),
+        ("/web-components.html", "#dropdowns"),
+        ("/web-components.html", "#copybuttons"),
+        ("/web-components.html", "#toggle-buttons"),
+        # The cards and tables provided by the theme cards extension
+        ("/cards.html", "#cards-and-tables"),
+        # Pages with deeply nested toctrees to stress the sidebar navigation
+        ("/subsections.html", ""),
+        # Using one of the simplest pages on the site, select the whole page
+        # for testing in order to effectively test repeated website elements
+        # like nav, sidebars, breadcrumbs, footer
+        ("/index.html", ""),  # select whole page
+    ],
+)
+def test_axe_core(
+    page: Page,
+    url_base: str,
+    theme: str,
+    url_pathname: str,
+    selector: str,
+):
+    """Should have no Axe-core violations at the provided theme and page section."""
+    # Load the page at the provided path
+    url_full = urljoin(url_base, url_pathname)
+    page.goto(url_full)
+
+    # Run a line of JavaScript that sets the light/dark theme on the page
+    page.evaluate(f"document.documentElement.dataset.theme = '{theme}'")
+
+    # Wait for CSS transitions (Bootstrap's transitions are 300 ms)
+    page.wait_for_timeout(301)
+
+    # Inject the Axe-core JavaScript library into the page
+    page.add_script_tag(path="node_modules/axe-core/axe.min.js")
+
+    # Run the Axe-core library against a section of the page (unless the
+    # selector is empty, then run against the whole page)
+    results = page.evaluate("axe.run()" if selector == "" else f"axe.run('{selector}')")
+
+    # Check found violations against known violations that we do not plan to fix
+    filtered_violations = filter_ignored_violations(results["violations"], url_pathname, theme)
+
+    assert len(filtered_violations) == 0, format_violations(filtered_violations)
+
+
+@pytest.mark.a11y
+def test_code_block_tab_stop(page: Page, url_base: str) -> None:
+    """Code blocks that have scrollable content should be tab stops."""
+    page.set_viewport_size({"width": 1440, "height": 720})
+    page.goto(urljoin(url_base, "/customizing.html"))
+
+    # This code-block contains a line long enough to overflow at narrow
+    # viewport widths (the "rtd_search_projects" example with a URL in it)
+    code_block = page.locator("css=#rtd-search-projects pre", has_text="rtd_search_projects")
+
+    # Viewport is wide, so code block content fits, no overflow, no tab stop
+    assert code_block.evaluate("el => el.scrollWidth > el.clientWidth") is False
+    assert code_block.evaluate("el => el.tabIndex") != 0
+
+    page.set_viewport_size({"width": 400, "height": 720})
+
+    # Narrow viewport, content overflows ...
+    assert code_block.evaluate("el => el.scrollWidth > el.clientWidth") is True
+
+    # ... and code block should be a tab stop.
+    #
+    # Note: expect() will wait until the expect condition is true (up to the
+    # test timeout limit). This is important because the resize handler is
+    # debounced.
+    expect(code_block).to_have_attribute("tabindex", "0")

sunpy_sphinx_theme-2.4.0/src/sunpy_sphinx_theme/tests/test_config_subtheme.py

@@ -0,0 +1,64 @@
+"""
+Tests relating to subthemes (i.e. astropy) setting config defaults.
+"""
+
+from sunpy_sphinx_theme.tests.helpers import inline_scripts
+
+
+def test_theme_defaults_of_derived_theme(sphinx_build_factory):
+    """
+    Test the theme.toml defaults of a theme derived from the sunpy theme.
+
+    Given a minimal theme that derives from the sunpy theme and sets defaults in its theme.toml
+    When the docs are built without any user theme options
+    Then the derived defaults apply to the navbar, the footer, the site root links and the search config
+    """
+    sphinx_build = sphinx_build_factory("derived").build()
+    html = sphinx_build.html_tree("index.html")
+
+    # The derived navbar_links default renders in the navbar
+    navbar = html.select_one("ul.bd-navbar-elements")
+    home = navbar.select_one('a[href="https://example.org/index.html"]')
+    assert home is not None
+    assert home.text.strip() == "Home"
+    docs = navbar.select_one('a[href="https://docs.example.org/"]')
+    assert docs is not None
+    assert docs.text.strip() == "Docs"
+
+    # The derived footer_links default renders in the footer
+    footer = html.select_one('.footer-links a[href="https://footer.example.org/"]')
+    assert footer is not None
+    assert footer.text.strip() == "Footer Example"
+
+    # The derived rtd_search_projects default is used by the search config script
+    search_config = [script for script in inline_scripts(html) if "set_search_config" in script]
+    assert len(search_config) == 1
+    assert '"name": "example"' in search_config[0]
+    assert '"link": "https://example.org/docs/"' in search_config[0]
+
+    # The sunpy theme.toml defaults still apply where the derived theme does not override
+    assert '"label": "Load more results"' in search_config[0]
+
+
+def test_no_search_projects(sphinx_build_factory, caplog):
+    """
+    Given a theme config where no sites are under "Documentation"
+    When built
+    Then RTD search config is disabled
+    """
+    config_toml = """\
+    [theme]
+    inherit = "sunpy"
+
+    [options]
+    sst_site_root = "https://astropy.org"
+
+    navbar_links = [
+        ["Home", "index.html", 2],
+        ["astropy", "https://docs.astropy.org/", 3],
+    ]
+    """
+    sphinx_build = sphinx_build_factory("derived", files={"theme/theme.toml": config_toml}).build()
+    html = sphinx_build.html_tree("index.html")
+    search_config = [script for script in inline_scripts(html) if "set_search_config" in script]
+    assert len(search_config) == 0

sunpy_sphinx_theme-2.4.0/src/sunpy_sphinx_theme/tests/test_goatcounter.py

@@ -0,0 +1,164 @@
+"""Tests for the goat counter analytics assets registered by the theme."""
+
+import pytest
+
+from sunpy_sphinx_theme.tests.helpers import inline_scripts, script_srcs
+
+SUNPY_GOAT_URL = "https://sunpy.goatcounter.com/count"
+GOATCOUNTER_COUNT_JS = "https://gc.zgo.at/count.js"
+
+
+def goatcounter_inline_script(html_tree):
+    """Return the inline script that configures window.goatcounter."""
+    scripts = [script for script in inline_scripts(html_tree) if "window.goatcounter" in script]
+    assert len(scripts) == 1
+    return scripts[0]
+
+
+def test_goatcounter_default_sunpy_site(sphinx_build_factory):
+    """
+    Test the goat counter default for the sunpy site root.
+
+    Given the docs are built with the default theme options
+    When a page is rendered
+    Then the inline script configures the sunpy goat counter and the goat counter script is loaded async
+    """
+    sphinx_build = sphinx_build_factory("base").build()
+    html = sphinx_build.html_tree("index.html")
+
+    # The inline script configures window.goatcounter for the sunpy domain
+    script = goatcounter_inline_script(html)
+    assert "var endpoint = '';" in script
+    assert "location.hostname.endsWith('sunpy.org')" in script
+    assert f"endpoint = '{SUNPY_GOAT_URL}'" in script
+
+    # The goat counter script itself is loaded async
+    count_js = html.select(f'script[src="{GOATCOUNTER_COUNT_JS}"]')
+    assert len(count_js) == 1
+    assert count_js[0].attrs["async"] == "async"
+
+
+def test_goatcounter_disabled_for_non_sunpy_site(sphinx_build_factory):
+    """
+    Test the goat counter for a non-sunpy site root.
+
+    Given the site root is a non-sunpy domain with no explicit goat counter URL
+    When a page is rendered
+    Then no goat counter assets are registered
+    """
+    confoverrides = {"html_theme_options": {"sst_site_root": "https://docs.example.org"}}
+    sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build()
+    html = sphinx_build.html_tree("index.html")
+
+    assert not [script for script in inline_scripts(html) if "window.goatcounter" in script]
+    assert GOATCOUNTER_COUNT_JS not in script_srcs(html)
+
+
+@pytest.mark.parametrize("scheme", ["https", "http"])
+def test_goatcounter_custom_url_for_non_sunpy_site(sphinx_build_factory, scheme):
+    """
+    Test an explicit goat counter URL for a non-sunpy site root.
+
+    Given the site root is a non-sunpy domain with an explicit goat counter URL
+    When a page is rendered
+    Then the inline script checks the site root without its scheme and uses the explicit URL
+    """
+    confoverrides = {
+        "html_theme_options": {
+            "sst_site_root": f"{scheme}://docs.example.org",
+            "goatcounter_analytics_url": "https://example.goatcounter.com/count",
+        },
+    }
+    sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build()
+    html = sphinx_build.html_tree("index.html")
+
+    script = goatcounter_inline_script(html)
+    assert "location.hostname.endsWith('docs.example.org')" in script
+    assert "endpoint = 'https://example.goatcounter.com/count'" in script
+    assert GOATCOUNTER_COUNT_JS in script_srcs(html)
+
+
+@pytest.mark.parametrize("disabled_value", [None, ""])
+def test_goatcounter_explicitly_disabled(sphinx_build_factory, disabled_value):
+    """Test explicitly disabling the goat counter.
+
+    Given the goat counter URL is set to a falsy value
+    When a page is rendered
+    Then no goat counter assets are registered
+    """
+    confoverrides = {"html_theme_options": {"goatcounter_analytics_url": disabled_value}}
+    sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build()
+    html = sphinx_build.html_tree("index.html")
+
+    assert not [script for script in inline_scripts(html) if "window.goatcounter" in script]
+    assert GOATCOUNTER_COUNT_JS not in script_srcs(html)
+
+
+@pytest.mark.parametrize(
+    ("endpoint", "default_line"),
+    [
+        ("https://test.example.com/count", "var endpoint = 'https://test.example.com/count';"),
+        (False, "var endpoint = '';"),
+    ],
+)
+def test_goatcounter_non_domain_endpoint(sphinx_build_factory, endpoint, default_line):
+    """Test the non-domain endpoint of the goat counter.
+
+    Given goatcounter_non_domain_endpoint is set to a URL or False
+    When a page is rendered
+    Then the default endpoint in the inline script matches the configured value
+    """
+    confoverrides = {"html_theme_options": {"goatcounter_non_domain_endpoint": endpoint}}
+    sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build()
+    html = sphinx_build.html_tree("index.html")
+
+    script = goatcounter_inline_script(html)
+    assert default_line in script
+
+
+def test_goatcounter_astropy(sphinx_build_factory):
+    """
+    Test astropy configuration setup.
+
+    Given the site root is astropy.org and the goat counter url is set.
+    When a page is rendered
+    Then the inline script adds the astropy goatcounter only on astropy.org sites.
+    """
+    confoverrides = {
+        "html_theme_options": {
+            "sst_site_root": "https://astropy.org",
+            "goatcounter_analytics_url": "https://astropy.goatcounter.com/count",
+        },
+    }
+    sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build()
+    html = sphinx_build.html_tree("index.html")
+
+    script = goatcounter_inline_script(html)
+    assert "var endpoint = '';" in script
+    assert "location.hostname.endsWith('astropy.org')" in script
+    assert "endpoint = 'https://astropy.goatcounter.com/count'" in script
+    assert GOATCOUNTER_COUNT_JS in script_srcs(html)
+
+
+def test_goat_counter_theme_defaults(sphinx_build_factory):
+    config_toml = """\
+    [theme]
+    inherit = "sunpy"
+
+    [options]
+    sst_site_root = "https://astropy.org"
+    goatcounter_analytics_url = "https://astropy.goatcounter.com/count"
+
+    navbar_links = [
+        ["Home", "index.html", 2],
+        ["astropy", "https://docs.astropy.org/", 3],
+    ]
+    """
+    sphinx_build = sphinx_build_factory("derived", files={"theme/theme.toml": config_toml}).build()
+    html = sphinx_build.html_tree("index.html")
+
+    script = goatcounter_inline_script(html)
+    assert "var endpoint = '';" in script
+    assert "location.hostname.endsWith('astropy.org')" in script
+    assert "endpoint = 'https://astropy.goatcounter.com/count'" in script
+    assert GOATCOUNTER_COUNT_JS in script_srcs(html)

sunpy_sphinx_theme-2.4.0/src/sunpy_sphinx_theme/tests/test_options.py

@@ -0,0 +1,17 @@
+from sunpy_sphinx_theme.tests.helpers import script_srcs, stylesheet_hrefs
+
+
+def test_rtd_search_disabled(sphinx_build_factory):
+    """Test disabling the search assets.
+
+    Given rtd_search is disabled
+    When a page is rendered
+    Then the search assets are not registered and the goat counter and submenu assets are unaffected
+    """
+    confoverrides = {"html_theme_options": {"rtd_search": False}}
+    sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build()
+    html = sphinx_build.html_tree("index.html")
+
+    srcs = script_srcs(html)
+    assert not any("js/rtd_enhanced_search.js" in src for src in srcs)
+    assert not any("css/rtd_enhanced_search.css" in href for href in stylesheet_hrefs(html))

{sunpy_sphinx_theme-2.3.0 → sunpy_sphinx_theme-2.4.0}/src/sunpy_sphinx_theme/theme/sunpy/theme.toml

@@ -71,10 +71,10 @@ footer_links = [
     ["Forum", "https://community.openastronomy.org/c/sunpy", 3],
     ["Chat", "https://openastronomy.element.io/#/room/#sunpy:openastronomy.org", 3],
 ]
-goatcounter_analytics_url = ""
-goatcounter_non_domain_endpoint = "False"
+goatcounter_analytics_url = "DEFAULT"  # Use a sentinel here to allow disabling by setting to false
+goatcounter_non_domain_endpoint = false
 pygment_light_style = "github-light"
-rtd_search = "True"
+rtd_search = true
 rtd_search_projects = ""
 rtd_extra_search_projects = ""
 rtd_search_load_more_label = "Load more results"

{sunpy_sphinx_theme-2.3.0 → sunpy_sphinx_theme-2.4.0}/src/sunpy_sphinx_theme.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sunpy-sphinx-theme
-Version: 2.3.0
+Version: 2.4.0
 Summary: The sphinx theme for the SunPy website and documentation.
 Author: The SunPy Developers
 License: BSD 2-Clause License
@@ -36,10 +36,10 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Framework :: Sphinx
 Classifier: Framework :: Sphinx :: Theme
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.9
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE.md
-Requires-Dist: pydata-sphinx-theme<0.23,>=0.22.0rc0
+Requires-Dist: pydata-sphinx-theme<0.24,>=0.22.0
 Requires-Dist: sphinxext-opengraph>=0.13
 Requires-Dist: sphinx>=7.3.0
 Provides-Extra: docs
@@ -50,6 +50,9 @@ Requires-Dist: sphinx-design; extra == "docs"
 Requires-Dist: sphinx-gallery; extra == "docs"
 Requires-Dist: sphinx-togglebutton; extra == "docs"
 Requires-Dist: sunpy; extra == "docs"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-playwright; extra == "test"
 Dynamic: license-file
 
 # SunPy Project Sphinx Theme

{sunpy_sphinx_theme-2.3.0 → sunpy_sphinx_theme-2.4.0}/src/sunpy_sphinx_theme.egg-info/SOURCES.txt

@@ -6,6 +6,9 @@ LICENSE.md
 MANIFEST.in
 README.md
 _typos.toml
+conftest.py
+flake.nix
+package.json
 pyproject.toml
 ruff.toml
 src/sunpy_sphinx_theme/__init__.py
@@ -19,6 +22,17 @@ src/sunpy_sphinx_theme.egg-info/requires.txt
 src/sunpy_sphinx_theme.egg-info/scm_file_list.json
 src/sunpy_sphinx_theme.egg-info/scm_version.json
 src/sunpy_sphinx_theme.egg-info/top_level.txt
+src/sunpy_sphinx_theme/tests/__init__.py
+src/sunpy_sphinx_theme/tests/helpers.py
+src/sunpy_sphinx_theme/tests/test_a11y.py
+src/sunpy_sphinx_theme/tests/test_config_subtheme.py
+src/sunpy_sphinx_theme/tests/test_goatcounter.py
+src/sunpy_sphinx_theme/tests/test_options.py
+src/sunpy_sphinx_theme/tests/sites/base/conf.py
+src/sunpy_sphinx_theme/tests/sites/base/index.rst
+src/sunpy_sphinx_theme/tests/sites/derived/conf.py
+src/sunpy_sphinx_theme/tests/sites/derived/index.rst
+src/sunpy_sphinx_theme/tests/sites/derived/theme/theme.toml
 src/sunpy_sphinx_theme/theme/sunpy/theme.toml
 src/sunpy_sphinx_theme/theme/sunpy/components/built-with.html
 src/sunpy_sphinx_theme/theme/sunpy/components/footer-links.html

{sunpy_sphinx_theme-2.3.0 → sunpy_sphinx_theme-2.4.0}/src/sunpy_sphinx_theme.egg-info/requires.txt

@@ -1,4 +1,4 @@
-pydata-sphinx-theme<0.23,>=0.22.0rc0
+pydata-sphinx-theme<0.24,>=0.22.0
 sphinxext-opengraph>=0.13
 sphinx>=7.3.0
 
@@ -10,3 +10,7 @@ sphinx-design
 sphinx-gallery
 sphinx-togglebutton
 sunpy
+
+[test]
+pytest>=7.0
+pytest-playwright

{sunpy_sphinx_theme-2.3.0 → sunpy_sphinx_theme-2.4.0}/src/sunpy_sphinx_theme.egg-info/scm_file_list.json

@@ -13,6 +13,7 @@
     "MANIFEST.in",
     "README.md",
     "_typos.toml",
+    "conftest.py",
     "docs/_static/img/Stuart-Mumford.png",
     "docs/cards.rst",
     "docs/code_ref/animals.rst",
@@ -32,11 +33,24 @@
     "examples/example_template.py",
     "examples/section/README.txt",
     "examples/section/example_template_subsection.py",
+    "flake.nix",
+    "package.json",
     "pyproject.toml",
     "ruff.toml",
     "src/sunpy_sphinx_theme/__init__.py",
     "src/sunpy_sphinx_theme/cards.py",
     "src/sunpy_sphinx_theme/conf.py",
+    "src/sunpy_sphinx_theme/tests/__init__.py",
+    "src/sunpy_sphinx_theme/tests/helpers.py",
+    "src/sunpy_sphinx_theme/tests/sites/base/conf.py",
+    "src/sunpy_sphinx_theme/tests/sites/base/index.rst",
+    "src/sunpy_sphinx_theme/tests/sites/derived/conf.py",
+    "src/sunpy_sphinx_theme/tests/sites/derived/index.rst",
+    "src/sunpy_sphinx_theme/tests/sites/derived/theme/theme.toml",
+    "src/sunpy_sphinx_theme/tests/test_a11y.py",
+    "src/sunpy_sphinx_theme/tests/test_config_subtheme.py",
+    "src/sunpy_sphinx_theme/tests/test_goatcounter.py",
+    "src/sunpy_sphinx_theme/tests/test_options.py",
     "src/sunpy_sphinx_theme/theme/sunpy/components/built-with.html",
     "src/sunpy_sphinx_theme/theme/sunpy/components/footer-links.html",
     "src/sunpy_sphinx_theme/theme/sunpy/components/navbar-logo.html",

sunpy_sphinx_theme-2.4.0/src/sunpy_sphinx_theme.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "2.4.0",
+  "distance": 0,
+  "node": "gfd0161cbb672c0deac5247be6eb7d34cd8082cc6",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-09-30"
+}

sunpy_sphinx_theme-2.3.0/src/sunpy_sphinx_theme.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "2.3.0",
-  "distance": 0,
-  "node": "g802a2218a32a8e8e4065daa33dcf2714523d779b",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-09-21"
-}