asterion-sphinx-style 0.1.0__tar.gz

asterion_sphinx_style-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,82 @@
+# Build on everything, publish only on a tag.
+#
+# The version is never written down: hatch-vcs derives it from the git tag, so a
+# release is `git tag vX.Y.Z && git push --tags` and nothing can drift. Two
+# consequences shape this file -- the checkout must be unshallow (a shallow one
+# hides tags and silently builds 0.0.0), and an off-tag or dirty build produces a
+# PEP 440 *local* version (`0.1.0.dev2+g1234abc`) which PyPI rejects. The guard
+# below turns that into a clear failure instead of a confusing upload error.
+name: publish
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # hatch-vcs reads tags
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      # A sphinx extension that fails to import is a broken release, and nothing
+      # else here would catch it: there is no test suite to run.
+      - name: Smoke-test the wheel
+        run: |
+          uv run --isolated --no-project --with dist/*.whl \
+            python -c "import asterion_sphinx_style as s; print(s.__version__); assert s.LOGO.is_file()"
+
+      - name: Check the version is publishable
+        run: |
+          version=$(ls dist/*.whl | head -1 | cut -d- -f2)
+          echo "built version: $version"
+          case "$version" in
+            *+*|*dev*)
+              echo "::error::'$version' is a local or dev version; PyPI will reject it."
+              echo "Tag a clean tree: git tag vX.Y.Z && git push --tags"
+              exit 1 ;;
+          esac
+          if [ "${GITHUB_REF_TYPE}" = "tag" ] && [ "${GITHUB_REF_NAME#v}" != "$version" ]; then
+            echo "::error::tag ${GITHUB_REF_NAME} and built version $version disagree."
+            exit 1
+          fi
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  # Split from `build` on purpose: this job has no checkout and runs no code of
+  # ours, so the OIDC token that can publish is exposed to as little as possible.
+  publish:
+    needs: build
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/asterion-sphinx-style
+    permissions:
+      id-token: write # trusted publishing; no API token to store or rotate
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

asterion_sphinx_style-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+_build/
+.ruff_cache/

asterion_sphinx_style-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

asterion_sphinx_style-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: asterion-sphinx-style
+Version: 0.1.0
+Summary: Asterion Robotics' sphinx style: a plain sphinx extension, usable in any sphinx project
+Author-email: Thibault Poignonec <t.poignonec@asterion-robotics.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: asterion,documentation,sphinx,theme
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: sphinx-rtd-theme>=3.0
+Requires-Dist: sphinx>=7.0
+Description-Content-Type: text/markdown
+
+# asterion_sphinx_style
+
+Sphinx style for Asterion public documentation.
+
+A plain sphinx extension, usable in any sphinx project:
+
+```python
+# conf.py
+extensions = ["asterion_sphinx_style"]
+```
+
+It configures [sphinx-rtd-theme](https://sphinx-rtd-theme.readthedocs.io/) rather than shipping a theme of its own, so everything a reader already knows about Read the Docs navigation still holds.
+
+## Install
+
+```bash
+pip install asterion-sphinx-style
+```
+
+If a project already builds its `extensions` list elsewhere, rebind rather than mutate:
+
+```python
+extensions = [*extensions, "asterion_sphinx_style"]
+```
+
+## Overriding
+
+Everything is applied **only when the project left it unset**, so your `conf.py` always wins:
+
+```python
+html_logo = "_static/my-logo.png"   # yours, not Asterion's
+html_theme = "furo"                 # the style stops configuring the theme
+```
+
+One caveat: `html_theme` reads as `alabaster` when a project has not chosen one, so a project that deliberately picks `alabaster` is indistinguishable from one that picked nothing, and the style will switch it to `sphinx_rtd_theme`. Any other theme is respected.
+
+## Palette
+
+Sampled from the logo wordmark and `AsterionReport.cls`. Contrast is against white, WCAG 2.1.
+
+| Role | Hex | Ratio | |
+|---|---|---|---|
+| Brand blue | `#0832F6` | 7.51:1 | AAA — safe for links and body text |
+| Deep blue | `#030189` | 15.33:1 | navigation header, admonition titles |
+| Navy | `#010042` | 19.45:1 | hover and visited states |
+| Alert red | `#DC0000` | 5.19:1 | danger and error admonitions only |
+
+## What it does, and what it deliberately does not
+
+Sets, when unset: `html_theme`, `html_logo`, `html_favicon`, and the theme's `style_nav_header_background`. Adds one stylesheet and its own static directory (appended, so your `_static` keeps precedence).
+
+It does **not** repaint the theme's navigation machinery — the current-page tree, expand/collapse states, light/dark alternation. That is a tuned system, and a style that rewrites it ends up fighting the theme on every release. Only surfaces that read as *brand* are touched.
+
+## Design rules
+
+A style is typically installed once and applied to every version of a site, including releases cut years earlier. Three rules follow:
+
+1. **Fill, never clobber** — a project's own settings always win.
+2. **Absolute paths, appended** — packaged assets by absolute path; `html_static_path` appended to on `builder-inited`, never assigned.
+3. **Never warn** — doc builds commonly run under `-W`, where one warning on one old page fails an entire site.
+
+## Versioning
+
+The git tag is the only version that exists; `pyproject.toml` is `dynamic` via `hatch-vcs`. A release is `git tag vX.Y.Z && git push --tags`.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE). The Asterion Robotics logo and name are trademarks of Asterion Robotics and are not covered by that grant.

asterion_sphinx_style-0.1.0/README.md

@@ -0,0 +1,68 @@
+# asterion_sphinx_style
+
+Sphinx style for Asterion public documentation.
+
+A plain sphinx extension, usable in any sphinx project:
+
+```python
+# conf.py
+extensions = ["asterion_sphinx_style"]
+```
+
+It configures [sphinx-rtd-theme](https://sphinx-rtd-theme.readthedocs.io/) rather than shipping a theme of its own, so everything a reader already knows about Read the Docs navigation still holds.
+
+## Install
+
+```bash
+pip install asterion-sphinx-style
+```
+
+If a project already builds its `extensions` list elsewhere, rebind rather than mutate:
+
+```python
+extensions = [*extensions, "asterion_sphinx_style"]
+```
+
+## Overriding
+
+Everything is applied **only when the project left it unset**, so your `conf.py` always wins:
+
+```python
+html_logo = "_static/my-logo.png"   # yours, not Asterion's
+html_theme = "furo"                 # the style stops configuring the theme
+```
+
+One caveat: `html_theme` reads as `alabaster` when a project has not chosen one, so a project that deliberately picks `alabaster` is indistinguishable from one that picked nothing, and the style will switch it to `sphinx_rtd_theme`. Any other theme is respected.
+
+## Palette
+
+Sampled from the logo wordmark and `AsterionReport.cls`. Contrast is against white, WCAG 2.1.
+
+| Role | Hex | Ratio | |
+|---|---|---|---|
+| Brand blue | `#0832F6` | 7.51:1 | AAA — safe for links and body text |
+| Deep blue | `#030189` | 15.33:1 | navigation header, admonition titles |
+| Navy | `#010042` | 19.45:1 | hover and visited states |
+| Alert red | `#DC0000` | 5.19:1 | danger and error admonitions only |
+
+## What it does, and what it deliberately does not
+
+Sets, when unset: `html_theme`, `html_logo`, `html_favicon`, and the theme's `style_nav_header_background`. Adds one stylesheet and its own static directory (appended, so your `_static` keeps precedence).
+
+It does **not** repaint the theme's navigation machinery — the current-page tree, expand/collapse states, light/dark alternation. That is a tuned system, and a style that rewrites it ends up fighting the theme on every release. Only surfaces that read as *brand* are touched.
+
+## Design rules
+
+A style is typically installed once and applied to every version of a site, including releases cut years earlier. Three rules follow:
+
+1. **Fill, never clobber** — a project's own settings always win.
+2. **Absolute paths, appended** — packaged assets by absolute path; `html_static_path` appended to on `builder-inited`, never assigned.
+3. **Never warn** — doc builds commonly run under `-W`, where one warning on one old page fails an entire site.
+
+## Versioning
+
+The git tag is the only version that exists; `pyproject.toml` is `dynamic` via `hatch-vcs`. A release is `git tag vX.Y.Z && git push --tags`.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE). The Asterion Robotics logo and name are trademarks of Asterion Robotics and are not covered by that grant.

asterion_sphinx_style-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "asterion-sphinx-style"
+dynamic = ["version"]
+description = "Asterion Robotics' sphinx style: a plain sphinx extension, usable in any sphinx project"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "Thibault Poignonec", email = "t.poignonec@asterion-robotics.com" }]
+keywords = ["sphinx", "theme", "documentation", "asterion"]
+classifiers = [
+    "Framework :: Sphinx :: Extension",
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+# A sphinx extension and nothing more. It carries the theme it configures, so a
+# bare `pip install` is enough.
+dependencies = [
+    "sphinx>=7.0",
+    "sphinx-rtd-theme>=3.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/asterion_sphinx_style"]
+
+# The git tag is the only version that exists; `fallback-version` keeps a
+# .git-less source export buildable.
+[tool.hatch.version]
+source = "vcs"
+fallback-version = "0.0.0"
+
+[tool.hatch.version.raw-options]
+version_scheme = "no-guess-dev"
+local_scheme = "node-and-date"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "C4", "SIM", "RUF", "ANN", "PTH"]

asterion_sphinx_style-0.1.0/src/asterion_sphinx_style/__init__.py

@@ -0,0 +1,114 @@
+# Copyright 2026 Asterion Robotics
+# SPDX-License-Identifier: Apache-2.0
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Author: Thibault Poignonec <t.poignonec@asterion-robotics.com>
+
+"""Asterion Robotics' sphinx style — a plain sphinx extension.
+
+Add it to any project's ``conf.py``::
+
+    extensions = ["asterion_sphinx_style"]
+
+It configures :mod:`sphinx_rtd_theme` rather than shipping a theme of its own,
+so everything a reader knows about Read the Docs' navigation still holds.
+
+Three rules govern everything here, because a style is typically installed once
+and applied to *every* version of a documentation site, including releases cut
+years earlier:
+
+1. **Fill, never clobber.** Every setting is applied only when the project left
+   it unset, so a repo's own ``conf.py`` always wins. That is what makes
+   overriding the logo a one-liner rather than a style option.
+2. **Absolute paths, appended.** Packaged assets are handed to sphinx by
+   absolute path and ``html_static_path`` is appended to on ``builder-inited``,
+   never assigned, so a project's own ``_static`` survives.
+3. **Never warn.** Documentation builds run under ``-W`` more often than not,
+   where a single warning on a single old page fails an entire site.
+
+The palette is the brand's, sampled from the logo and the report template.
+Every colour clears WCAG AA against both white and its own foreground; the
+brand blue clears AAA on white.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # pragma: no cover - typing only, keeps import cost at zero
+    from sphinx.application import Sphinx
+    from sphinx.config import Config
+
+try:  # pragma: no cover - trivial, and untestable from a source checkout
+    from importlib.metadata import PackageNotFoundError, version
+
+    __version__ = version("asterion-sphinx-style")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0"
+
+BRAND_BLUE = "#0832F6"
+"""The wordmark blue. 7.51:1 on white — AAA for body text, so it is safe for links."""
+
+DEEP_BLUE = "#030189"
+"""``AsterionBlueInner``, the report cover's gradient centre. Brand surfaces."""
+
+NAVY = "#010042"
+"""``AsterionBlueOuter``, the gradient edge. Deeper surfaces and hover states."""
+
+ALERT_RED = "#DC0000"
+"""The report's confidential stamp. Danger admonitions only."""
+
+THEME = "sphinx_rtd_theme"
+SPHINX_DEFAULT_THEME = "alabaster"
+"""What ``html_theme`` reads as when a project has not chosen one."""
+
+STATIC_DIR = Path(__file__).parent / "static"
+STYLESHEET = "asterion.css"
+LOGO = STATIC_DIR / "asterion-logo.png"
+"""The white wordmark: the navigation header it sits on is a dark brand block."""
+FAVICON = STATIC_DIR / "asterion-favicon.png"
+
+
+def _apply_defaults(_app: Sphinx, config: Config) -> None:
+    """Fill in what the project left unset. Never overwrite a deliberate choice."""
+    if config.html_theme in ("", SPHINX_DEFAULT_THEME):
+        config.html_theme = THEME
+    if not config.html_logo:
+        config.html_logo = str(LOGO)
+    if not config.html_favicon:
+        config.html_favicon = str(FAVICON)
+
+    # Theme options are per-theme, so only touch them when the theme is ours.
+    # setdefault, not assignment: a project may have set some of these already.
+    if config.html_theme == THEME:
+        options: dict[str, Any] = dict(config.html_theme_options or {})
+        options.setdefault("style_nav_header_background", DEEP_BLUE)
+        config.html_theme_options = options
+
+
+def _register_static(app: Sphinx) -> None:
+    """Append, so a project's own ``_static`` keeps precedence."""
+    app.config.html_static_path.append(str(STATIC_DIR))
+
+
+def setup(app: Sphinx) -> dict[str, Any]:
+    app.connect("config-inited", _apply_defaults)
+    app.connect("builder-inited", _register_static)
+    app.add_css_file(STYLESHEET)
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

asterion_sphinx_style-0.1.0/src/asterion_sphinx_style/static/asterion.css

@@ -0,0 +1,173 @@
+/* Copyright 2026 Asterion Robotics
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Asterion's brand layer over sphinx-rtd-theme.
+ *
+ * Deliberately small. The theme's navigation mechanics -- the current-page
+ * tree, its expand/collapse states, its light/dark alternation -- are a tuned
+ * system, and repainting them wholesale is how a style ends up fighting the
+ * theme on every release. This restyles the surfaces that read as *brand* (the
+ * header block, the mobile bar, links) and leaves the machinery alone.
+ *
+ * Palette, sampled from the logo and the report class:
+ *   #0832F6  brand blue   wordmark        7.51:1 on white (AAA)
+ *   #030189  deep blue    gradient centre 15.33:1
+ *   #010042  navy         gradient edge   19.45:1
+ *   #DC0000  alert red    confidential     5.19:1
+ */
+
+:root {
+  --asterion-brand: #0832f6;
+  --asterion-deep: #030189;
+  --asterion-navy: #010042;
+  --asterion-alert: #dc0000;
+
+  /* Sidebar tints. The theme builds its navigation out of neutral greys; these
+   * are the same lightness steps pulled toward the brand hue, so the structure
+   * survives and only the colour changes. Every pairing below clears WCAG AA. */
+  /* Both are kept light and near-neutral on purpose. A saturated blue on a
+   * saturated navy reads flat however good its contrast ratio looks: hue
+   * similarity undercuts luminance separation. Hierarchy therefore comes from
+   * tint (white caption over tinted links) rather than from dimming anything. */
+  --asterion-nav-text: #dde3ff; /* 15.28:1 on navy */
+  --asterion-nav-caption: #ffffff; /* 19.45:1 on navy, and bold + uppercase */
+  --asterion-nav-current: #eef1ff; /* the "you are here" block */
+  --asterion-nav-current-2: #dce2ff; /* one level deeper */
+}
+
+/* --- brand surfaces ------------------------------------------------------ */
+
+/* Also set via `style_nav_header_background`; kept here so the block still
+   looks right if a project overrides html_theme_options wholesale. */
+.wy-side-nav-search,
+.wy-nav-top {
+  background-color: var(--asterion-deep);
+}
+
+/* The wordmark is wide and the theme sizes logos for square marks. */
+.wy-side-nav-search > a img.logo {
+  max-width: 12rem;
+  padding: 0.35rem 0;
+}
+
+/* The project name under the logo duplicates the wordmark. */
+.wy-side-nav-search > div.version {
+  color: rgba(255, 255, 255, 0.75);
+}
+
+.wy-side-nav-search input[type="text"] {
+  border-color: var(--asterion-navy);
+}
+
+/* --- sidebar navigation -------------------------------------------------- */
+
+/* The theme's nav is a grey system: a dark panel, and a light block marking the
+ * section you are in. That structure is good and is kept; every grey in it is
+ * re-tinted to the brand. Brand blue cannot be used as *text* on the dark panel
+ * (1.72:1 against the theme's #343131, and no better on navy), so it appears
+ * where it is legible: as the L1 heading on the light block, and as fills. */
+
+.wy-nav-side {
+  background: var(--asterion-navy);
+}
+
+.wy-menu-vertical a {
+  color: var(--asterion-nav-text);
+}
+
+.wy-menu-vertical a:hover {
+  background-color: var(--asterion-deep);
+  color: #fff;
+}
+
+.wy-menu-vertical header,
+.wy-menu-vertical p.caption {
+  color: var(--asterion-nav-caption);
+}
+
+/* The current section's block, and its L1 heading in Asterion blue. */
+.wy-menu-vertical li.current {
+  background: var(--asterion-nav-current);
+}
+
+.wy-menu-vertical li.current > a,
+.wy-menu-vertical li.on a {
+  color: var(--asterion-brand);
+  background: #fff;
+}
+
+.wy-menu-vertical li.current > a:hover,
+.wy-menu-vertical li.on a:hover {
+  background: var(--asterion-nav-current);
+}
+
+/* Descendants sit on the light block, so they take the darkest brand tone. */
+.wy-menu-vertical li.current a {
+  color: var(--asterion-navy);
+  border-right-color: var(--asterion-nav-current-2);
+}
+
+.wy-menu-vertical li.current a:hover {
+  background: var(--asterion-nav-current-2);
+}
+
+.wy-menu-vertical li.toctree-l2.current > a,
+.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a {
+  background: var(--asterion-nav-current-2);
+}
+
+/* Expand arrows inherit from their row rather than the theme's grey ramp. */
+.wy-menu-vertical li button.toctree-expand {
+  color: var(--asterion-nav-text);
+}
+
+.wy-menu-vertical li.current > a button.toctree-expand,
+.wy-menu-vertical li.on a button.toctree-expand,
+.wy-menu-vertical li.current a button.toctree-expand {
+  color: var(--asterion-brand);
+}
+
+/* --- links --------------------------------------------------------------- */
+
+.rst-content a,
+.wy-nav-content a {
+  color: var(--asterion-brand);
+}
+
+.rst-content a:hover,
+.wy-nav-content a:hover {
+  color: var(--asterion-deep);
+}
+
+/* The theme ships purple (#9b59b6) here, which belongs to a different palette.
+ * Navy keeps the "where have I been" affordance inside the brand. */
+.rst-content a:visited,
+.wy-nav-content a:visited {
+  color: var(--asterion-navy);
+}
+
+/* Headerlinks are decoration; brand blue on hover is enough. */
+.rst-content .headerlink {
+  color: var(--asterion-brand);
+}
+
+/* --- accents ------------------------------------------------------------- */
+
+.rst-content .admonition-title {
+  background-color: var(--asterion-deep);
+}
+
+.rst-content .danger .admonition-title,
+.rst-content .error .admonition-title {
+  background-color: var(--asterion-alert);
+}
+
+.rst-content .note,
+.rst-content .admonition {
+  border-left: 3px solid var(--asterion-deep);
+}
+
+.rst-content .danger,
+.rst-content .error {
+  border-left-color: var(--asterion-alert);
+}