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

{sunpy_sphinx_theme-2.2.2 → sunpy_sphinx_theme-2.4.0}/.readthedocs.yaml

@@ -2,7 +2,7 @@ version: 2
 build:
   os: ubuntu-lts-latest
   tools:
-    python: "mambaforge-latest"
+    python: "miniforge3-latest"
   jobs:
     post_checkout:
       - git fetch --unshallow || true

{sunpy_sphinx_theme-2.2.2 → 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.2.2 → sunpy_sphinx_theme-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sunpy-sphinx-theme
-Version: 2.2.2
+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.19,>=0.17
+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.2.2 → sunpy_sphinx_theme-2.4.0}/_typos.toml

@@ -21,4 +21,5 @@ default.extend-ignore-identifiers-re = [
     "ot",
     # Coords,
     "pn",
+    "CPY",
 ]

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.2.2 → 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.17,<0.19",
+  "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.2.2 → sunpy_sphinx_theme-2.4.0}/ruff.toml

@@ -31,6 +31,7 @@ lint.extend-ignore = [
     "PLR2004", # Magic value used in comparison
     "TD002", # Missing author in TODO
     "TD003", # Missing issue link on the line following this TODO
+    "CPY001", # Copyright in each file
 ]
 
 [lint.per-file-ignores]
@@ -48,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.2.2 → 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))
@@ -122,6 +125,28 @@ def update_html_context(app: Sphinx, pagename: str, templatename: str, context,
     context["sst_pathto"] = partial(sst_pathto, context)
 
 
+def _get_sphinx_gallery_thumbnail(doctree):
+    """
+    Return the generated Sphinx-Gallery thumbnail for an example page.
+    """
+    source = doctree.get("source")
+    if not source:
+        return None
+
+    source_path = Path(source)
+    thumbnail_dir = source_path.parent / "images" / "thumb"
+    if not thumbnail_dir.is_dir():
+        return None
+
+    # Reuse the thumbnail Sphinx-Gallery already picked for this page.
+    thumbnails = sorted(thumbnail_dir.glob(f"sphx_glr_{source_path.stem}_thumb.*"))
+    for thumbnail in thumbnails:
+        if thumbnail.suffix.lower() in SPHINX_GALLERY_IMAGE_EXTENSIONS:
+            return thumbnail
+
+    return None
+
+
 def update_opengraph_context(app: Sphinx, pagename: str, templatename: str, context, doctree) -> None:  # NOQA: ARG001
     """
     Add Sphinx-Gallery images to the Open Graph metadata context.
@@ -133,6 +158,13 @@ def update_opengraph_context(app: Sphinx, pagename: str, templatename: str, cont
     if "og:image" in metadata:
         return
 
+    # Prefer the user defined generated gallery thumbnail when one exists.
+    if thumbnail := _get_sphinx_gallery_thumbnail(doctree):
+        metadata["og:image"] = posixpath.join(app.builder.imagedir, thumbnail.name)
+        context["meta"] = metadata
+        return
+
+    # Fall back to the first gallery image
     for node in doctree.findall():
         if node.__class__.__name__ != "imgsgnode" or not node.get("uri"):
             continue
@@ -159,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"""
@@ -198,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,
@@ -241,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/" },
+]