scverse-doc 0.0.1__py3-none-any.whl

scverse_doc/__init__.py

@@ -0,0 +1,57 @@
+"""The scverse Sphinx theme and shared documentation configuration.
+
+A package’s `conf.py` needs few lines:
+
+.. code:: python
+
+   extensions = ["scverse_doc"]
+
+   source_repository = "https://github.com/scverse/pertpy"
+
+This extension sets up the subextensions,
+each of which also works on its own:
+
+:mod:`scverse_doc.autodoc`
+    The layout of the API pages.
+:mod:`scverse_doc.config`
+    The extension stack and the shared defaults.
+:mod:`scverse_doc.napoleon`
+    Prose return sections in NumPy-style docstrings.
+:mod:`scverse_doc.registry`
+    The package registry, usable as an :func:`~scverse_doc.registry.intersphinx` mapping.
+:mod:`scverse_doc.source`
+    The repository links: the header icon, “edit this page”, and ``[source]``.
+:mod:`scverse_doc.theme`
+    The theme, its chrome, and the per-package accent.
+
+Anything set in `conf.py` wins.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sphinx.util.typing import ExtensionMetadata
+
+from . import autodoc, config, napoleon, registry, source, theme
+from .config import _is_set_by_user
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+    from sphinx.config import Config
+
+__all__ = ["autodoc", "config", "napoleon", "registry", "source", "theme", "setup"]
+
+
+def _default_theme(app: Sphinx, config: Config) -> None:
+    """Select the theme, since the umbrella extension means it too, unless `conf.py` picked another."""
+    if not _is_set_by_user(config, "html_theme"):
+        config.html_theme = "scverse"
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    """Set up the registry and the subextensions."""
+    for extension in set(__all__) - {"setup"}:
+        app.setup_extension(f"scverse_doc.{extension}")
+    app.connect("config-inited", _default_theme)
+    return ExtensionMetadata(parallel_read_safe=True)

scverse_doc/_accents.json

@@ -0,0 +1,12 @@
+{
+    "default": "#262fb5",
+    "anndata": "#e5864b",
+    "mudata": "#4ab274",
+    "muon": "#6cf1a1",
+    "pertpy": "#da347f",
+    "scanpy": "#de367b",
+    "scirpy": "#da347f",
+    "scvi-tools": "#fbb822",
+    "spatialdata": "#40a9ff",
+    "squidpy": "#969dea"
+}

scverse_doc/_color.py

@@ -0,0 +1,145 @@
+"""Colour maths for deriving accessible accent shades.
+
+Package accents are chosen for brand recognition, not for contrast.
+Several of the accents scverse already uses (``#6cf1a1`` for muon, ``#fbb822`` for scvi-tools)
+fail WCAG AA as text colours on white, and others fail on a dark background.
+So the raw accent is only ever used for decorative surfaces,
+and text/link colours are *derived* from it here by moving lightness until the contrast target is met,
+keeping hue and saturation intact so the result still reads as the package’s colour.
+"""
+
+from __future__ import annotations
+
+import colorsys
+import re
+from typing import NamedTuple
+
+__all__ = ["contrast_ratio", "derive_readable", "parse_hex", "relative_luminance"]
+
+#: Minimum contrast ratio for normal-size body text under WCAG 2.1 AA.
+WCAG_AA_NORMAL = 4.5
+
+_HEX_RE = re.compile(r"\A#?(?P<digits>[0-9a-fA-F]{3}|[0-9a-fA-F]{6})\Z")
+
+
+class RGB(NamedTuple):
+    """An sRGB colour with channels in ``[0, 1]``."""
+
+    r: float
+    g: float
+    b: float
+
+    def to_hex(self) -> str:
+        """Render as a lowercase ``#rrggbb`` string."""
+        return "#" + "".join(f"{round(c * 255):02x}" for c in self)
+
+
+def parse_hex(color: str) -> RGB:
+    """Parse a CSS hex colour.
+
+    Parameters
+    ----------
+    color
+        A ``#rgb`` or ``#rrggbb`` string, with or without the leading ``#``.
+
+    Returns
+    -------
+    The colour, with channels normalised to ``[0, 1]``.
+
+    Raises
+    ------
+    ValueError
+        If `color` is not a three- or six-digit hex colour.
+    """
+    if (m := _HEX_RE.match(color.strip())) is None:
+        msg = f"Not a hex colour: {color!r}"
+        raise ValueError(msg)
+    digits = m["digits"]
+    if len(digits) == 3:
+        digits = "".join(d * 2 for d in digits)
+    return RGB(*(c / 255 for c in bytes.fromhex(digits)))
+
+
+def _to_linear(channel: float) -> float:
+    """Undo the sRGB transfer function for a single channel."""
+    return channel / 12.92 if channel <= 0.04045 else ((channel + 0.055) / 1.055) ** 2.4
+
+
+def relative_luminance(color: RGB | str) -> float:
+    """Compute the WCAG relative luminance of a colour.
+
+    Parameters
+    ----------
+    color
+        An :class:`RGB` colour or a hex string.
+
+    Returns
+    -------
+    Relative luminance in ``[0, 1]``, where 0 is black and 1 is white.
+    """
+    r, g, b = parse_hex(color) if isinstance(color, str) else color
+    return 0.2126 * _to_linear(r) + 0.7152 * _to_linear(g) + 0.0722 * _to_linear(b)
+
+
+def contrast_ratio(fg: RGB | str, bg: RGB | str) -> float:
+    """Compute the WCAG contrast ratio between two colours.
+
+    Parameters
+    ----------
+    fg
+        Foreground colour.
+    bg
+        Background colour.
+
+    Returns
+    -------
+    A ratio between 1 (identical) and 21 (black on white).
+    """
+    lum_a, lum_b = relative_luminance(fg), relative_luminance(bg)
+    lighter, darker = max(lum_a, lum_b), min(lum_a, lum_b)
+    return (lighter + 0.05) / (darker + 0.05)
+
+
+def derive_readable(accent: str, background: str, *, target: float = WCAG_AA_NORMAL) -> str:
+    """Derive a text-safe variant of `accent` that meets `target` contrast against `background`.
+
+    Hue and saturation are preserved and only lightness is moved,
+    so the result still reads as the same colour.
+    Lightness moves away from the background:
+    darker on a light background, lighter on a dark one.
+
+    Parameters
+    ----------
+    accent
+        The brand accent to adjust, as a hex string.
+    background
+        The background the derived colour will sit on, as a hex string.
+    target
+        The contrast ratio to reach.
+
+    Returns
+    -------
+    A hex colour meeting `target` where that is achievable by lightness alone,
+    otherwise the closest achievable colour, which is black or white.
+
+    Examples
+    --------
+    >>> derive_readable("#fbb822", "#ffffff")  # scvi-tools yellow, unreadable as-is
+    '#9d6d03'
+    """
+    if contrast_ratio(accent, background) >= target:
+        return parse_hex(accent).to_hex()
+
+    hue, lightness, saturation = colorsys.rgb_to_hls(*parse_hex(accent))
+    darken = relative_luminance(background) > 0.5
+    step = -1 / 512 if darken else 1 / 512
+
+    # Candidates are checked after rounding to 8-bit hex:
+    # a float lightness that clears the target can fall back under it once quantized,
+    # which is how #e5864b and #fbb822 ended up one hundredth short of AA.
+    while 0.0 <= (lightness := lightness + step) <= 1.0:
+        candidate = parse_hex(RGB(*colorsys.hls_to_rgb(hue, lightness, saturation)).to_hex())
+        if contrast_ratio(candidate, background) >= target:
+            return candidate.to_hex()
+
+    return "#000000" if darken else "#ffffff"

scverse_doc/autodoc/__init__.py

@@ -0,0 +1,70 @@
+"""The layout of the API pages.
+
+Ships :mod:`~sphinx.ext.autosummary` templates for modules and classes.
+A class page gets tables of its attributes and methods, then their documentation,
+with each attribute documented as a property, method or plain attribute as appropriate.
+Templates of the same name in your own `templates_path` still win.
+
+Also hides ``object``, :class:`~typing.Generic` and private classes from the bases
+that ``:show-inheritance:`` lists.
+"""
+
+from __future__ import annotations
+
+import traceback
+from pathlib import Path
+from typing import TYPE_CHECKING, Generic, Literal, get_origin
+
+from jinja2.defaults import DEFAULT_FILTERS  # type: ignore[attr-defined]
+from sphinx.ext.autodoc import import_object
+from sphinx.util import logging
+from sphinx.util.typing import ExtensionMetadata
+
+if TYPE_CHECKING:
+    from typing import Any
+
+    from sphinx.application import Sphinx
+    from sphinx.config import Config
+
+__all__ = ["setup"]
+
+_logger = logging.getLogger(__name__)
+
+TEMPLATES = Path(__file__).parent / "templates"
+
+
+def _member_type(obj_path: str) -> Literal["method", "property", "attribute"]:
+    """Determine what kind of member `obj_path` is, for ``.. auto{{ fullname | member_type }}::``."""
+    cls_path, cls_name, member_name = obj_path.rsplit(".", 2)
+    try:
+        cls = import_object(cls_path, [cls_name], "class")[-1]
+    except ImportError:
+        _logger.error(f"Failed to import {cls_name} from {cls_path}: {traceback.format_exc()}")
+        return "attribute"
+    match getattr(cls, member_name, None):
+        case property():
+            return "property"
+        case member if callable(member):
+            return "method"
+        case _:
+            return "attribute"
+
+
+def _skip_private_bases(app: Sphinx, name: str, obj: type, options: Any, bases: list[type]) -> None:
+    bases[:] = [b for b in bases if b is not object and get_origin(b) is not Generic and not b.__name__.startswith("_")]
+
+
+def _add_templates(app: Sphinx, config: Config) -> None:
+    # Appended, so the package’s own templates win.
+    config.templates_path = [*config.templates_path, str(TEMPLATES)]
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    """Register the templates, their filter, and the bases hook."""
+    app.setup_extension("sphinx.ext.autodoc")
+    app.setup_extension("sphinx.ext.autosummary")
+    # TODO: autosummary builds its own jinja environment with no hook for filters, so this is global.
+    DEFAULT_FILTERS["member_type"] = _member_type
+    app.connect("config-inited", _add_templates)
+    app.connect("autodoc-process-bases", _skip_private_bases)
+    return ExtensionMetadata(parallel_read_safe=True)

scverse_doc/autodoc/templates/autosummary/class.rst

@@ -0,0 +1,54 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. add toctree option to make autodoc generate the pages
+
+.. autoclass:: {{ fullname }}
+
+{% set methods = methods | select("ne", "__init__") | list %}
+
+{% block attributes %}
+{% for item in attributes %}
+{% if loop.first %}
+    Attributes table
+    ~~~~~~~~~~~~~~~~
+
+    .. autosummary::
+{% endif %}
+       ~{{ item }}
+{%- endfor %}
+{% endblock %}
+
+{% block methods %}
+{% for item in methods %}
+{% if loop.first %}
+    Methods table
+    ~~~~~~~~~~~~~
+
+    .. autosummary::
+{% endif %}
+       ~{{ item }}
+{% endfor %}
+{% endblock %}
+
+{% block attributes_documentation %}
+{% for item in attributes %}
+{% if loop.first %}
+    Attributes
+    ~~~~~~~~~~
+
+{% endif %}
+    .. auto{{ [fullname, item] | join(".") | member_type }}:: {{ [fullname, item] | join(".") }}
+{%- endfor %}
+{% endblock %}
+
+{% block methods_documentation %}
+{% for item in methods %}
+{% if loop.first %}
+    Methods
+    ~~~~~~~
+{% endif %}
+    .. automethod:: {{ [fullname, item] | join(".") }}
+{%- endfor %}
+{% endblock %}

scverse_doc/autodoc/templates/autosummary/module.rst

@@ -0,0 +1,62 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+    {% block attributes %}
+    {% if attributes %}
+    .. rubric:: {{ _('Module Attributes') }}
+
+    .. autosummary::
+    {% for item in attributes %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block functions %}
+    {% if functions %}
+    .. rubric:: {{ _('Functions') }}
+
+    .. autosummary::
+        :toctree:
+    {% for item in functions %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block classes %}
+    {% if classes %}
+    .. rubric:: {{ _('Classes') }}
+
+    .. autosummary::
+        :toctree:
+    {% for item in classes %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block exceptions %}
+    {% if exceptions %}
+    .. rubric:: {{ _('Exceptions') }}
+
+    .. autosummary::
+        :toctree:
+    {% for item in exceptions %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

scverse_doc/config.py

@@ -0,0 +1,90 @@
+"""The extension stack and the shared defaults.
+
+Sets up the extensions in :data:`EXTENSIONS`, so `conf.py` lists only ``scverse_doc``,
+and fills in :data:`DEFAULTS`. Anything set in `conf.py` always wins.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from sphinx.util.typing import ExtensionMetadata
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+    from sphinx.config import Config
+
+__all__ = ["DEFAULTS", "EXTENSIONS", "MYST_ENABLE_EXTENSIONS", "setup"]
+
+#: Extensions set up alongside this one,
+#: so packages list only ``scverse_doc``.
+EXTENSIONS = (
+    "myst_nb",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "sphinx_copybutton",
+    "sphinx_design",
+    "sphinxext.opengraph",
+)
+
+#: The MyST syntax extensions, i.e. the ``myst_enable_extensions`` entry of :data:`~scverse_doc.config.DEFAULTS`.
+MYST_ENABLE_EXTENSIONS = (
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "html_image",
+    "html_admonition",
+)
+
+#: Sphinx config values applied unless `conf.py` sets them.
+DEFAULTS: dict[str, Any] = {
+    "autosummary_generate": True,
+    "autodoc_member_order": "groupwise",
+    "napoleon_google_docstring": False,
+    "napoleon_numpy_docstring": True,
+    "napoleon_include_init_with_doc": False,
+    "napoleon_use_param": True,
+    "napoleon_use_rtype": True,
+    "default_role": "literal",
+    "myst_enable_extensions": list(MYST_ENABLE_EXTENSIONS),
+    "myst_heading_anchors": 6,
+    "source_suffix": {".rst": "restructuredtext", ".md": "myst-nb", ".ipynb": "myst-nb"},
+    # Off: tutorials needing a GPU or a large download must not gate a docs build.
+    "nb_execution_mode": "off",
+    "nb_output_stderr": "remove",
+    "nb_merge_streams": True,
+    # One unreachable host must not stall the build.
+    "intersphinx_timeout": 10,
+    "exclude_patterns": ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"],
+    "nitpicky": True,
+}
+
+
+def _is_set_by_user(config: Config, name: str) -> bool:
+    """Report whether `conf.py` or a ``-D`` override set `name`."""
+    return name in config._raw_config or name in config._overrides
+
+
+def _apply_defaults(config: Config) -> None:
+    """Fill in the values `conf.py` did not set."""
+    for name, value in DEFAULTS.items():
+        if _is_set_by_user(config, name):
+            continue
+        setattr(config, name, value)
+
+
+def _configure(app: Sphinx, config: Config) -> None:
+    _apply_defaults(config)
+    if not _is_set_by_user(config, "html_title"):
+        config.html_title = config.project
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    """Set up the extension stack and apply the defaults."""
+    for extension in EXTENSIONS:
+        app.setup_extension(extension)
+    app.connect("config-inited", _configure)
+    return ExtensionMetadata(parallel_read_safe=True)

scverse_doc/napoleon.py

@@ -0,0 +1,54 @@
+"""Prose return sections in NumPy-style docstrings.
+
+:mod:`sphinx.ext.napoleon` reads a NumPy-style ``Returns`` section as a list of ``name : type`` entries.
+With this extension, it can be prose instead:
+
+.. code:: rst
+
+   Returns
+   -------
+   The fitted model, or `None` if `copy` is false.
+
+Lines that do look like ``name : type`` become an item linking to `type`.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from sphinx.ext.napoleon import NumpyDocstring  # type: ignore[attr-defined]
+from sphinx.util.typing import ExtensionMetadata
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+
+    from sphinx.application import Sphinx
+
+__all__ = ["setup"]
+
+
+def _process_return(lines: Iterable[str]) -> Iterator[str]:
+    for line in lines:
+        if m := re.fullmatch(r"(?P<param>\w+)\s+:\s+(?P<type>[\w.]+)", line):
+            yield f"-{m['param']} (:class:`~{m['type']}`)"
+        else:
+            yield line
+
+
+def _parse_returns_section(self: NumpyDocstring, section: str) -> list[str]:
+    lines_raw = self._dedent(self._consume_to_next_section())
+    if lines_raw and lines_raw[0] == ":":
+        del lines_raw[0]
+    lines = self._format_block(":returns: ", list(_process_return(lines_raw)))
+    if lines and lines[-1]:
+        lines.append("")
+    return lines
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    """Set up napoleon and make it read ``Returns`` sections as prose."""
+    app.setup_extension("sphinx.ext.napoleon")
+    # TODO: patches private napoleon API; replace once napoleon has a hook for this.
+    NumpyDocstring._parse_returns_section = _parse_returns_section  # type: ignore[method-assign,assignment]
+    return ExtensionMetadata(parallel_read_safe=True)