diff --git a/docs/conf.py b/docs/conf.py index c774315d4..a0e338006 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -38,6 +38,7 @@ "tutorials/notebooks/*.rst", # exclude all 0.x.y.md files, but not index.md "release-notes/[!i]*.md", + "news.md", # is `include`d into index.md ] pygments_style = "sphinx" @@ -62,6 +63,7 @@ "IPython.sphinxext.ipython_console_highlighting", "patch_sphinx_toolbox_autoprotocol", "sphinx_toolbox.more_autodoc.autoprotocol", + "patch_myst_cite", ] myst_enable_extensions = [ "html_image", # So README.md can be used on github and sphinx docs @@ -109,10 +111,6 @@ ("py:class", "anndata._core.sparse_dataset.BaseCompressedSparseDataset"), ("py:obj", "numpy._typing._array_like._ScalarType_co"), ] -suppress_warnings = [ - "ref.citation", - "myst.header", # https://github.com/executablebooks/MyST-Parser/issues/262 -] def setup(app: Sphinx): diff --git a/docs/extensions/patch_myst_cite.py b/docs/extensions/patch_myst_cite.py new file mode 100644 index 000000000..3b8afd34a --- /dev/null +++ b/docs/extensions/patch_myst_cite.py @@ -0,0 +1,33 @@ +"""Override MyST’s cite role with one that works.""" + +from __future__ import annotations + +from types import MappingProxyType +from typing import TYPE_CHECKING + +from docutils import nodes, utils + +if TYPE_CHECKING: + from collections.abc import Mapping, Sequence + from typing import Any + + from docutils.parsers.rst.states import Inliner + from sphinx.application import Sphinx + + +def cite_role( # noqa: PLR0917 + name: str, + rawsource: str, + text: str, + lineno: int, + inliner: Inliner, + options: Mapping[str, Any] = MappingProxyType({}), + content: Sequence[str] = (), +) -> tuple[list[nodes.Node], list[nodes.system_message]]: + key = utils.unescape(text) + node = nodes.citation_reference(f"[{key}]_", key) + return [node], [] + + +def setup(app: Sphinx): + app.add_role("cite", cite_role, override=True) diff --git a/docs/news.md b/docs/news.md index d68fc74d4..a6faab17e 100644 --- a/docs/news.md +++ b/docs/news.md @@ -1,6 +1,6 @@ # Muon paper published {small}`2022-02-02` -Muon has been published in Genome Biology [Bredikhin22]_. +Muon has been published in Genome Biology {cite}`Bredikhin22`. Muon is a framework for multimodal data built on top of `AnnData`. Check out [Muon](https://muon.readthedocs.io/en/latest/) and its datastructure [MuData](https://mudata.readthedocs.io/en/latest/). diff --git a/docs/references.rst b/docs/references.rst index 86427809f..5da6d4cd9 100644 --- a/docs/references.rst +++ b/docs/references.rst @@ -20,7 +20,3 @@ References Murphy (2012, *Machine Learning: A Probabilistic Perspective*, MIT Press https://mitpress.mit.edu/9780262018029/machine-learning/. - -.. [Wolf18] Wolf *et al.* (2018), - *Scanpy: large-scale single-cell gene expression data analysis*, - Genome Biology https://doi.org/10.1186/s13059-017-1382-0.