feat: source links

README.md

@@ -13,17 +13,17 @@ Install it, and a package's `conf.py` becomes:
 ```python
 extensions = ["scverse_doc"]
 
-html_theme_options = {"repo": "scverse/pertpy"}
+source_repository = "https://github.com/scverse/pertpy"
 ```
 
-That gets you the scverse brand and dark mode, the shared navbar, footer, and announcement banner, a "scverse packages" dropdown generated from the package registry, cross-links to every core package, and the standard extension stack.
+That gets you the scverse brand and dark mode, the shared navbar, footer, and announcement banner, a "scverse packages" dropdown generated from the package registry, cross-links to every core package, the repository links ("edit this page" and the navbar icon), and the standard extension stack.
 
 Every piece also works on its own. For the theme without the extension stack or the shared defaults, select it and leave `extensions` alone – it is a registered Sphinx theme, so installing the package is enough:
 
 ```python
 html_theme = "scverse"
 
-html_theme_options = {"repo": "scverse/pertpy"}
+source_repository = "https://github.com/scverse/pertpy"
 ```
 
 ## Getting started

docs/api.md

@@ -11,6 +11,7 @@
 
 api/config.md
 api/theme.md
+api/source.md
 api/registry.md
 ```
 
@@ -30,6 +31,11 @@ Registers the theme and its {ref}`theme options <theme-options>`.
 Selecting it with `html_theme = "scverse"` is enough on its own –
 it is a registered Sphinx theme, so it needs no `extensions` entry.
 
+## {doc}`api/source`
+
+Repository links – the navbar icon, “edit this page”, and `[source]` –
+from the {ref}`source_* config values <source-options>`, for whichever theme is selected.
+
 ## {doc}`api/registry`
 
 ```{eval-rst}

docs/api/source.md

@@ -0,0 +1,76 @@
+# `scverse_doc.source`
+
+```{eval-rst}
+.. automodule:: scverse_doc.source
+```
+
+(source-options)=
+
+## Configuration
+
+```{confval} source_repository
+:type: str
+:default: `""`
+
+The repository URL, e.g. `"https://gitlab.com/owner/name"`.
+Empty means no repository links at all.
+```
+
+```{confval} source_branch
+:type: str
+:default: `$READTHEDOCS_GIT_IDENTIFIER`, else `"main"`
+
+The ref the links point at.
+Read the Docs pull request builds fall back to the default, since they identify by PR number.
+```
+
+```{confval} source_directory
+:type: str
+:default: `"docs"`
+
+Where the documentation sources live in the repository.
+```
+
+```{confval} source_code_directory
+:type: str
+:default: `"src"`
+
+Where the importable code lives in the repository, for the `[source]` links.
+Set it to `""` for a flat layout.
+```
+
+```{confval} source_provider
+:type: str
+:default: inferred from the host
+
+Which forge’s URL layout the repository follows:
+`"github"`, `"gitlab"` or `"bitbucket"`.
+Inferring it works for the hosted instances and for self-hosted ones whose host
+name contains the forge’s (`gitlab.example.org`); name it for anything else.
+An unknown forge still gets the navbar icon, just no per-page links.
+```
+
+## What each theme gets
+
+| Theme | Reads |
+| --- | --- |
+| `pydata-sphinx-theme`, and so {doc}`ours <theme>` | `html_context`’s `{provider}_user`/`_repo`/`_version`/`_url` and `doc_path`, plus `use_edit_page_button` |
+| `sphinx_rtd_theme` | the same, plus `display_{provider}`, `{provider}_host` and `conf_py_path` |
+| `furo`, and anything else on `sphinx-basic-ng` | the `source_repository`/`source_branch`/`source_directory` theme options, plus `display_{provider}` for its footer icon – which it shows on Read the Docs only |
+| `sphinx-book-theme` | the `repository_url`/`repository_branch`/`repository_provider`/`path_to_docs` theme options, plus `use_repository_button`, `use_source_button` and `use_issues_button` |
+
+Only the options a theme declares are written; a theme that declares none of them –
+`alabaster`, say – is left alone. Anything `conf.py` set itself wins.
+
+## `[source]` links
+
+Listing {mod}`sphinx.ext.linkcode` is enough; the resolver is filled in:
+
+```python
+extensions = ["scverse_doc.source", "sphinx.ext.linkcode"]
+
+source_repository = "https://github.com/scverse/pertpy"
+# no need to define `linkcode_resolve`
+```
+
+A `linkcode_resolve` of your own still wins.

docs/api/theme.md

@@ -10,6 +10,7 @@
 
 `html_theme_options` keys this theme adds. Everything else there is
 [pydata-sphinx-theme’s](https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html).
+The repository links have their own {ref}`config values <source-options>`.
 
 ```{confval} package
 :type: str
@@ -18,28 +19,6 @@
 The registry name to look the accent and the dropdown’s current entry up under.
 ```
 
-```{confval} repo
-:type: str
-:default: `""`
-
-`owner/name` on GitHub. Adds the navbar icon and the “edit this page” button.
-```
-
-```{confval} branch
-:type: str
-:default: `$READTHEDOCS_GIT_IDENTIFIER`, else `"main"`
-
-The ref {confval}`repo`’s edit links point at.
-Read the Docs pull request builds fall back to the default, since they identify by PR number.
-```
-
-```{confval} doc_path
-:type: str
-:default: `"docs/"`
-
-Where the documentation sources live in {confval}`repo`.
-```
-
 ```{confval} accent
 :type: str
 :default: the registry accent, else the scverse primary

docs/conf.py

@@ -1,8 +1,9 @@
 """Sphinx docs configuration."""
 
 project = "scverse-doc"
-extensions = ["scverse_doc", "sphinxcontrib.bibtex"]
-html_theme_options = {"repo": "scverse/scverse-doc", "announcement": ""}
+extensions = ["scverse_doc", "sphinxcontrib.bibtex", "sphinx.ext.linkcode"]
+html_theme_options = {"announcement": ""}
+source_repository = "https://github.com/scverse/scverse-doc"
 
 bibtex_bibfiles = ["references.bib"]
 

pyproject.toml

@@ -48,9 +48,11 @@ dev = [
 ]
 test = [
   "coverage>=7.10",
-  "defusedxml",     # for sphinx.testing’s HTML assertions
+  "defusedxml",        # for sphinx.testing’s HTML assertions
+  "furo",              # to check `scverse_doc.source` against a non-pydata theme
   "pytest",
-  "pytest-cov",     # For VS Code’s coverage functionality
+  "pytest-cov",        # For VS Code’s coverage functionality
+  "sphinx-book-theme",
 ]
 doc = [
   "ipykernel",
@@ -138,6 +140,10 @@ addopts = [
   "--import-mode=importlib", # allow using test files with same name
   "--doctest-modules",
 ]
+filterwarnings = [
+  "error",
+  "ignore::PendingDeprecationWarning:sphinx_book_theme",
+]
 strict = true
 testpaths = [ "tests", "src" ]
 

scripts/sync_brand_tokens.py

@@ -87,7 +87,7 @@ def render_region(scss: str, indent: str) -> str:
         msg = f"SCSS variables vanished from the website: {', '.join('$' + m for m in missing)}"
         raise KeyError(msg)
 
-    values = {**LITERALS, **{prop: variables[scss_name] for scss_name, prop in TOKEN_MAP.items()}}
+    values = LITERALS | {prop: variables[scss_name] for scss_name, prop in TOKEN_MAP.items()}
     lines = [BEGIN, *(f"{prop}-light: {value};" for prop, value in values.items()), END]
     return "\n".join(indent + line for line in lines)
 

src/scverse_doc/__init__.py

@@ -6,7 +6,7 @@
 
    extensions = ["scverse_doc"]
 
-   html_theme_options = {"repo": "scverse/pertpy"}
+   source_repository = "https://github.com/scverse/pertpy"
 
 This extension sets up the subextensions,
 each of which also works on its own:
@@ -15,6 +15,8 @@
     The extension stack and the shared defaults.
 :mod:`scverse_doc.registry`
     The package registry, usable as an :func:`~scverse_doc.registry.intersphinx` mapping.
+:mod:`scverse_doc.source`
+    The repository links: the navbar icon, “edit this page”, and ``[source]``.
 :mod:`scverse_doc.theme`
     The theme, its chrome, and the per-package accent.
 
@@ -27,14 +29,14 @@
 
 from sphinx.util.typing import ExtensionMetadata
 
-from . import config, registry, theme
+from . import config, registry, source, theme
 from .config import _is_set_by_user
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
     from sphinx.config import Config
 
-__all__ = ["config", "registry", "theme", "setup"]
+__all__ = ["config", "registry", "source", "theme", "setup"]
 
 
 def _default_theme(app: Sphinx, config: Config) -> None:

src/scverse_doc/registry.py

@@ -197,7 +197,7 @@ def intersphinx(*extra: str, external: bool = True, core: bool = True) -> ChainM
     >>> intersphinx_mapping["scanpy"]  # doctest: +ELLIPSIS
     ('https://scanpy.scverse.org/...', None)
 
-    >>> intersphinx_mapping = {**intersphinx(), "my_package": ("...", None)}
+    >>> intersphinx_mapping = intersphinx() | {"my_package": ("...", None)}
     >>> intersphinx_mapping["my_package"]
     ('...', None)
     """