From a45754f421376631e93218f473e7eb28b516e68f Mon Sep 17 00:00:00 2001 From: Intron7 Date: Mon, 26 Oct 2026 15:23:21 +0100 Subject: [PATCH 1/8] move to scverse-docs Signed-off-by: Intron7 --- docs/_static/css/override.css | 12 ---- docs/_templates/autosummary/class.rst | 67 -------------------- docs/conf.py | 89 ++++----------------------- pyproject.toml | 9 +-- 4 files changed, 14 insertions(+), 163 deletions(-) delete mode 100644 docs/_templates/autosummary/class.rst diff --git a/docs/_static/css/override.css b/docs/_static/css/override.css index ec6f0cab..3c26d0d5 100644 --- a/docs/_static/css/override.css +++ b/docs/_static/css/override.css @@ -18,15 +18,3 @@ dl.citation > dt { .pr { font-size: 70% !important; } - -/* RSC colors are -#7400ff - violet -#76b900 - green -#4169e1 - blue -*/ - -p.caption .caption-text { - color: #7400ff; - font-weight: 600; - text-transform: uppercase; -} diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst deleted file mode 100644 index 30a299db..00000000 --- a/docs/_templates/autosummary/class.rst +++ /dev/null @@ -1,67 +0,0 @@ -{{ fullname | escape | underline}} - -.. currentmodule:: {{ module }} - -.. add toctree option to make autodoc generate the pages - -.. autoclass:: {{ objname }} - -{% block attributes %} -{% if attributes %} -Attributes table -~~~~~~~~~~~~~~~~~~ - -.. autosummary:: -{% for item in attributes %} - ~{{ objname }}.{{ item }} -{%- endfor %} -{% endif %} -{% endblock %} - -{% block methods %} -{% if methods %} -Methods table -~~~~~~~~~~~~~ - -.. autosummary:: -{% for item in methods %} - {%- if item != '__init__' %} - ~{{ objname }}.{{ item }} - {%- endif -%} -{%- endfor %} -{% endif %} -{% endblock %} - -{% block attributes_documentation %} -{% if attributes %} -Attributes -~~~~~~~~~~~ - -{% for item in attributes %} - -{{ item }} -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. autoattribute:: {{ [objname, item] | join(".") }} -{%- endfor %} - -{% endif %} -{% endblock %} - -{% block methods_documentation %} -{% if methods %} -Methods -~~~~~~~ - -{% for item in methods %} -{%- if item != '__init__' %} - -{{ item }} -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. automethod:: {{ [objname, item] | join(".") }} -{%- endif -%} -{%- endfor %} - -{% endif %} -{% endblock %} diff --git a/docs/conf.py b/docs/conf.py index 20a8194e..1a5bf7c5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -2,15 +2,16 @@ # -- Path setup -------------------------------------------------------------- import sys -import os from datetime import datetime from importlib.metadata import metadata -from pathlib import Path, PurePosixPath +from pathlib import Path from typing import TYPE_CHECKING import anndata # noqa import fast_array_utils # noqa from docutils import nodes from docutils.parsers.rst import roles +from scverse_doc.config import DEFAULTS +from scverse_doc.registry import intersphinx if TYPE_CHECKING: from sphinx.application import Sphinx @@ -19,9 +20,6 @@ HERE = Path(__file__).parent sys.path.insert(0, str(HERE.parent / "src/")) -on_rtd = os.environ.get("READTHEDOCS") == "True" -rtd_links_prefix = PurePosixPath("src") - # -- Project information ----------------------------------------------------- info = metadata("rapids_singlecell") @@ -31,15 +29,14 @@ author = info["Author"] copyright = f"{datetime.now():%Y}, {author}" version = info["Version"] -repository_url = "https://github.com/scverse/rapids-singlecell" +source_repository = "https://github.com/scverse/rapids-singlecell" # The full version, including alpha/beta/rc tags release = info["Version"] templates_path = ["_templates"] bibtex_bibfiles = ["references.bib"] -nitpicky = True # Warn about broken links -needs_sphinx = "4.5" +needs_sphinx = "8.1" suppress_warnings = [ "ref.citation", "myst.header", # https://github.com/executablebooks/MyST-Parser/issues/262 @@ -48,30 +45,21 @@ # -- General configuration --------------------------------------------------- extensions = [ - "myst_nb", - "sphinx_design", - "sphinx.ext.autodoc", + "scverse_doc", # sets up napoleon, so needs to be before sphinx_autodoc_typehints "sphinx.ext.doctest", "sphinx.ext.coverage", "sphinx.ext.mathjax", - "sphinx.ext.autosummary", - "sphinx.ext.napoleon", - "sphinx.ext.intersphinx", "sphinx.ext.githubpages", "sphinx_autodoc_typehints", "sphinx.ext.extlinks", "sphinx.ext.imgconverter", - "sphinx_copybutton", "nbsphinx", - "scanpydoc", "scverse_misc.sphinx_ext", "sphinx.ext.linkcode", "sphinx_tabs.tabs", - "sphinxext.opengraph", "sphinxcontrib.bibtex", ] -autosummary_generate = True autodoc_member_order = "bysource" autodoc_mock_imports = [ "cudf", @@ -82,49 +70,18 @@ "pylibraft", "cuvs", ] -default_role = "literal" -napoleon_google_docstring = False -napoleon_numpy_docstring = True -napoleon_include_init_with_doc = False napoleon_use_rtype = False # having a separate entry generally helps readability -napoleon_use_param = True api_dir = HERE / "api" -myst_enable_extensions = [ - "amsmath", - "colon_fence", - "deflist", - "dollarmath", - "html_image", - "html_admonition", -] myst_url_schemes = ("http", "https", "mailto", "ftp") -nb_output_stderr = "remove" -nb_execution_mode = "off" -nb_merge_streams = True typehints_defaults = "braces" -source_suffix = { - ".rst": "restructuredtext", - ".ipynb": "myst-nb", - ".myst": "myst-nb", -} - -intersphinx_mapping = { - "anndata": ("https://anndata.scverse.org/en/stable/", None), - "numpy": ("https://numpy.org/doc/stable/", None), - "scipy": ("https://docs.scipy.org/doc/scipy/", None), +# scverse core packages, Python, NumPy, SciPy, pandas and Matplotlib come from the registry +intersphinx_mapping = intersphinx("squidpy", "spatialdata", "pertpy", "decoupler") | { "cupy": ("https://docs.cupy.dev/en/stable/", None), - "python": ("https://docs.python.org/3", None), "cuml": ("https://docs.rapids.ai/api/cuml/stable/", None), - "pandas": ("https://pandas.pydata.org/docs/", None), "cudf": ("https://docs.rapids.ai/api/cudf/stable/", None), "cugraph": ("https://docs.rapids.ai/api/cugraph/stable/", None), - "scanpy": ("https://scanpy.scverse.org/en/stable/", None), - "squidpy": ("https://squidpy.readthedocs.io/en/stable/", None), - "spatialdata": ("https://spatialdata.scverse.org/en/stable/", None), - "pertpy": ("https://pertpy.scverse.org/en/stable/", None), "seaborn": ("https://seaborn.pydata.org/", None), - "decoupler": ("https://decoupler.readthedocs.io/en/latest/", None), "rmm": ("https://docs.rapids.ai/api/rmm/stable/", None), "statsmodels": ("https://www.statsmodels.org/stable/", None), "omnipath": ("https://omnipath.readthedocs.io/en/latest/", None), @@ -135,11 +92,8 @@ # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. exclude_patterns = [ - "_build", - "Thumbs.db", - ".DS_Store", + *DEFAULTS.exclude_patterns, "._*", - "*.ipynb_checkpoints", "release-notes/blank.md", ] @@ -158,11 +112,8 @@ # -- Options for HTML output ------------------------------------------------- -html_theme = "scanpydoc" html_theme_options = { - "repository_url": repository_url, - "repository_branch": os.environ.get("READTHEDOCS_GIT_IDENTIFIER", "main"), - "use_repository_button": True, + "accent": "#7400ff", "navigation_with_keys": False, "show_toc_level": 2, } @@ -170,20 +121,13 @@ html_logo = "_static/logo_RTD.svg" html_static_path = ["_static"] html_css_files = ["css/override.css"] -html_title = "rapids-singlecell" # OpenGraph metadata for social media previews ogp_site_url = "https://rapids-singlecell.readthedocs.io/" ogp_site_name = "rapids-singlecell" ogp_image = "_static/logo_RTD.svg" -qualname_overrides = { - "numpy.bool_": "numpy.bool", # Since numpy 2, numpy.bool is the canonical dtype - # Since numpy 2.5, NDArray is a TypeAliasType defined in numpy._typing._array_like, - # so a subscripted NDArray[...] reports that private module and sphinx-autodoc-typehints - # builds the target as . -- a name numpy does not - # document. Same treatment as anndata gives the pre-2.5 spelling of this alias. - "numpy._typing._array_like.GenericAlias": ("py:data", "numpy.typing.NDArray"), +xref_overrides = { "spatialdata._core.spatialdata.SpatialData": "spatialdata.SpatialData", } @@ -215,17 +159,6 @@ def setup(app: Sphinx) -> None: """App setup hook.""" app.add_role("small", roles.GenericRole("small", nodes.inline)) app.add_role("smaller", roles.GenericRole("smaller", nodes.inline)) - app.add_config_value( - "recommonmark_config", - default={ - "auto_toc_tree_section": "Contents", - "enable_auto_toc_tree": True, - "enable_math": True, - "enable_inline_math": False, - "enable_eval_rst": True, - }, - rebuild=True, - ) # extlinks config diff --git a/pyproject.toml b/pyproject.toml index 87844675..d8005d64 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -52,15 +52,12 @@ rapids-cu12 = [ [dependency-groups] docs = [ - "sphinx>=4.5.0", - "sphinx-copybutton", + "sphinx>=8.1", "nbsphinx>=0.8.12", - "myst-nb", - "sphinx-design", "sphinx-tabs", - "sphinxext-opengraph", "sphinxcontrib.bibtex", - "scanpydoc[typehints,theme]>=0.9.4", + "scverse-doc[full]>=0.3", + "sphinx-autodoc-typehints", "scverse-misc[sphinx]>=0.1.3", "dask", "pytest", From bf852e220a3e82d89c2709182f4523ae08c2456e Mon Sep 17 00:00:00 2001 From: Intron7 Date: Mon, 26 Oct 2026 15:38:03 +0100 Subject: [PATCH 2/8] add release note and change colors Signed-off-by: Intron7 --- docs/conf.py | 3 ++- docs/release-notes/0.19.0.md | 5 +++++ docs/release-notes/index.md | 4 ++++ 3 files changed, 11 insertions(+), 1 deletion(-) create mode 100644 docs/release-notes/0.19.0.md diff --git a/docs/conf.py b/docs/conf.py index 1a5bf7c5..85699f37 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -113,7 +113,8 @@ # -- Options for HTML output ------------------------------------------------- html_theme_options = { - "accent": "#7400ff", + "accent": "#007c91", # teal blue + "secondary_accent": "#76b900", # NVIDIA green "navigation_with_keys": False, "show_toc_level": 2, } diff --git a/docs/release-notes/0.19.0.md b/docs/release-notes/0.19.0.md new file mode 100644 index 00000000..1e6c1edc --- /dev/null +++ b/docs/release-notes/0.19.0.md @@ -0,0 +1,5 @@ +### 0.19.0 {small}`the-future` + +```{rubric} Misc +``` +* Switch the documentation theme from `scanpydoc` to the shared scverse theme `scverse-doc` {pr}`856` {smaller}`S Dicks` diff --git a/docs/release-notes/index.md b/docs/release-notes/index.md index 38ad8399..e9766690 100644 --- a/docs/release-notes/index.md +++ b/docs/release-notes/index.md @@ -2,6 +2,10 @@ # Release notes +## Version 0.19.0 +```{include} /release-notes/0.19.0.md +``` + ## Version 0.18.0 ```{include} /release-notes/0.18.1.md ``` From a5534e48a5e2534f11a64a77b97b21f718943e98 Mon Sep 17 00:00:00 2001 From: Intron7 Date: Mon, 26 Oct 2026 22:10:32 +0100 Subject: [PATCH 3/8] address review comments: drop sphinx-tabs and needs_sphinx, update accent colors Signed-off-by: Intron7 --- docs/conf.py | 6 ++---- pyproject.toml | 1 - 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 85699f37..80445c81 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -36,7 +36,6 @@ templates_path = ["_templates"] bibtex_bibfiles = ["references.bib"] -needs_sphinx = "8.1" suppress_warnings = [ "ref.citation", "myst.header", # https://github.com/executablebooks/MyST-Parser/issues/262 @@ -56,7 +55,6 @@ "nbsphinx", "scverse_misc.sphinx_ext", "sphinx.ext.linkcode", - "sphinx_tabs.tabs", "sphinxcontrib.bibtex", ] @@ -113,8 +111,8 @@ # -- Options for HTML output ------------------------------------------------- html_theme_options = { - "accent": "#007c91", # teal blue - "secondary_accent": "#76b900", # NVIDIA green + "accent": "#8E93F0", # violet + "secondary_accent": "#F59A3A", # orange "navigation_with_keys": False, "show_toc_level": 2, } diff --git a/pyproject.toml b/pyproject.toml index d8005d64..5b8eb9f0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -54,7 +54,6 @@ rapids-cu12 = [ docs = [ "sphinx>=8.1", "nbsphinx>=0.8.12", - "sphinx-tabs", "sphinxcontrib.bibtex", "scverse-doc[full]>=0.3", "sphinx-autodoc-typehints", From 394f4f05d095a3bbfd801e265bf64afe8d977836 Mon Sep 17 00:00:00 2001 From: Intron7 Date: Mon, 26 Oct 2026 22:18:43 +0100 Subject: [PATCH 4/8] take accent colors from the scverse website Signed-off-by: Intron7 --- docs/conf.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 80445c81..8af19cb7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -111,8 +111,7 @@ # -- Options for HTML output ------------------------------------------------- html_theme_options = { - "accent": "#8E93F0", # violet - "secondary_accent": "#F59A3A", # orange + "secondary_accent": True, # second brand colour from the scverse website "navigation_with_keys": False, "show_toc_level": 2, } From 89e8b0bff4f8037fd7197691b0394a3a32b4eb07 Mon Sep 17 00:00:00 2001 From: Intron7 Date: Mon, 26 Oct 2026 22:36:27 +0100 Subject: [PATCH 5/8] set accent colors explicitly until scverse-doc syncs them Signed-off-by: Intron7 --- docs/conf.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 8af19cb7..bd488d24 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -111,7 +111,9 @@ # -- Options for HTML output ------------------------------------------------- html_theme_options = { - "secondary_accent": True, # second brand colour from the scverse website + # TODO: drop once scverse-doc is released with the website accents (scverse/scverse-doc#78) + "accent": "#8E93F0", # violet + "secondary_accent": "#F59A3A", # orange "navigation_with_keys": False, "show_toc_level": 2, } From 6191ee490ead6e2abe0b25fefe37b433fee3e361 Mon Sep 17 00:00:00 2001 From: Intron7 Date: Mon, 26 Oct 2026 23:02:54 +0100 Subject: [PATCH 6/8] use the original violet and green accents Signed-off-by: Intron7 --- docs/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index bd488d24..a591dcc8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -112,8 +112,8 @@ html_theme_options = { # TODO: drop once scverse-doc is released with the website accents (scverse/scverse-doc#78) - "accent": "#8E93F0", # violet - "secondary_accent": "#F59A3A", # orange + "accent": "#7400ff", # violet + "secondary_accent": "#76b900", # NVIDIA green "navigation_with_keys": False, "show_toc_level": 2, } From bd08a4b155bd6c660026d98cf8648ba5d3cdbace Mon Sep 17 00:00:00 2001 From: Intron7 Date: Mon, 26 Oct 2026 23:14:04 +0100 Subject: [PATCH 7/8] swap accents so sidebar captions are violet Signed-off-by: Intron7 --- docs/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index a591dcc8..613191d7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -112,8 +112,8 @@ html_theme_options = { # TODO: drop once scverse-doc is released with the website accents (scverse/scverse-doc#78) - "accent": "#7400ff", # violet - "secondary_accent": "#76b900", # NVIDIA green + "accent": "#76b900", # NVIDIA green + "secondary_accent": "#7400ff", # violet, used for the sidebar captions "navigation_with_keys": False, "show_toc_level": 2, } From d1739a81397c10fdb28a56af5ef6904bcb9d90d2 Mon Sep 17 00:00:00 2001 From: Intron7 Date: Mon, 26 Oct 2026 23:19:49 +0100 Subject: [PATCH 8/8] brighten the link hover color in dark mode Signed-off-by: Intron7 --- docs/_static/css/override.css | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/_static/css/override.css b/docs/_static/css/override.css index 3c26d0d5..069075b6 100644 --- a/docs/_static/css/override.css +++ b/docs/_static/css/override.css @@ -18,3 +18,9 @@ dl.citation > dt { .pr { font-size: 70% !important; } + +/* scverse-doc mixes the link hover colour towards the (near-white) text colour, + which greys out the accent in dark mode. Brighten it instead, keeping chroma and hue. */ +html[data-theme="dark"] { + --pst-color-primary-highlight: oklch(from var(--scverse-color-accent-text) calc(l + 0.08) c h); +}