diff --git a/docs/_static/css/override.css b/docs/_static/css/override.css index ec6f0cab..069075b6 100644 --- a/docs/_static/css/override.css +++ b/docs/_static/css/override.css @@ -19,14 +19,8 @@ dl.citation > dt { 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; +/* 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); } 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..613191d7 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,13 @@ 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" suppress_warnings = [ "ref.citation", "myst.header", # https://github.com/executablebooks/MyST-Parser/issues/262 @@ -48,30 +44,20 @@ # -- 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 +68,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 +90,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 +110,10 @@ # -- 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, + # TODO: drop once scverse-doc is released with the website accents (scverse/scverse-doc#78) + "accent": "#76b900", # NVIDIA green + "secondary_accent": "#7400ff", # violet, used for the sidebar captions "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/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 ``` diff --git a/pyproject.toml b/pyproject.toml index 87844675..5b8eb9f0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -52,15 +52,11 @@ 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",