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

sunpy_sphinx_theme-2.5.0/.codespellrc

@@ -0,0 +1,2 @@
+[codespell]
+ignore-words-list = ANDed,arange,iy1,iy2,EIS,eis,EIT,eit,HAE,his,His,nd,NDData,along,alog10,FOVs,FOV,OT,ot,pn,CPY

{sunpy_sphinx_theme-2.3.0 → sunpy_sphinx_theme-2.5.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.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sunpy-sphinx-theme
-Version: 2.3.0
+Version: 2.5.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.25,>=0.24.0
 Requires-Dist: sphinxext-opengraph>=0.13
 Requires-Dist: sphinx>=7.3.0
 Provides-Extra: docs
@@ -50,6 +50,12 @@ 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"
+Provides-Extra: test-playwright
+Requires-Dist: playwright==1.64.1; extra == "test-playwright"
+Requires-Dist: pytest-playwright==0.10.0; extra == "test-playwright"
+Requires-Dist: playwright-figure-tests; extra == "test-playwright"
 Dynamic: license-file
 
 # SunPy Project Sphinx Theme

sunpy_sphinx_theme-2.5.0/conftest.py

@@ -0,0 +1,143 @@
+"""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="session")
+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.5.0/flake.nix

@@ -0,0 +1,35 @@
+{
+  description = "sunpy-sphinx-theme dev shell (provides Playwright browsers for NixOS)";
+
+  inputs = {
+    flake-parts.url = "github:hercules-ci/flake-parts";
+    nixpkgs.url = "https://channels.nixos.org/nixos-unstable/nixexprs.tar.zst";
+  };
+
+  outputs = { flake-parts, ... } @ inputs: flake-parts.lib.mkFlake { inherit inputs; } {
+    perSystem = { config, self', inputs', pkgs, system, ... }: {
+      devShells.default = pkgs.mkShell {
+        # playwright-driver.browsers provides Firefox/Chromium patched to run on
+        # NixOS. The pip `playwright` package reads PLAYWRIGHT_BROWSERS_PATH and
+        # uses these browsers directly; its version must match whatever nixpkgs
+        # pins here. nodejs is for the a11y env's npm install (axe-core).
+        # bash is needed so `nix develop --command` can evaluate shellHook
+        # (the devShell otherwise has no shell on PATH).
+        packages = with pkgs; [
+          bash
+          nodejs_latest
+          playwright-test
+          playwright-driver.browsers
+        ];
+
+        shellHook = ''
+          export PLAYWRIGHT_BROWSERS_PATH=${pkgs.playwright-driver.browsers}
+          export PLAYWRIGHT_SKIP_VALIDATE_HOST_REQUIREMENTS=true
+          # Browsers installed by nix so no-op the install command in tox
+          export PLAYWRIGHT_INSTALL_CMD="python -c pass"
+        '';
+      };
+    };
+    systems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
+  };
+}

sunpy_sphinx_theme-2.5.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.5.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.24.0,<0.25",
   "sphinxext-opengraph>=0.13",
   "sphinx>=7.3.0"
 ]
@@ -37,6 +37,14 @@ docs = [
   "sphinx-togglebutton",
   "sunpy",
 ]
+test = [
+  "pytest>=7.0",
+]
+test-playwright = [
+  "playwright==1.64.1",
+  "pytest-playwright==0.10.0",
+  "playwright-figure-tests",
+]
 
 [project.entry-points]
 "sphinx.html_themes" = { sunpy = "sunpy_sphinx_theme" }
@@ -46,6 +54,13 @@ 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", "-m not mpl_image_compare and not a11y"]
+mpl-results-path = "figure_test_images"
+mpl-use-full-test-name = true
+
 [ tool.gilesbot ]
   [ tool.gilesbot.circleci_artifacts.giles ]
     enabled = false
@@ -65,6 +80,11 @@ include-package-data = true
     message = "sunpy docs with devdeps preview"
     report_on_fail = true
 
+  [ tool.gilesbot.circleci_artifacts.visual-tests-summary ]
+    url = "fig_comparison.html"
+    message = "screenshot test summary page"
+    report_on_fail = true
+
   [ tool.gilesbot.circleci_artifacts.astropy_website ]
     url = "astropy.org/_build/html/index.html"
     message = "Astropy website preview"

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

@@ -49,17 +49,16 @@ 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)
+    "PLR0913", # Too many arguments in function definition
+    "PLR0917", # Too many positional arguments
 ]
 
 [lint.pydocstyle]

{sunpy_sphinx_theme-2.3.0 → sunpy_sphinx_theme-2.5.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.5.0/src/sunpy_sphinx_theme/tests/__init__.py

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

sunpy_sphinx_theme-2.5.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.5.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.5.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.5.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.5.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.5.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/" },
+]