Fix references

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):

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)

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/).

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.