Backport PR #2901: Doc submodule (#2962)

Co-authored-by: Isaac Virshup <ivirshup@gmail.com>

Author: meeseeksmachine

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "notebooks"]
+	path = notebooks
+	url = https://github.com/scverse/scanpy-tutorials/

.readthedocs.yml

@@ -1,4 +1,6 @@
 version: 2
+submodules:
+  include: all
 build:
   os: ubuntu-20.04
   tools:

docs/_tutorials.md

@@ -11,7 +11,7 @@
 The plotting module {mod}`scanpy.pl` largely parallels the `tl.*` and a few of the `pp.*` functions.
 For most tools and for some preprocessing functions, you'll find a plotting function with the same name.
 
-See {doc}`tutorials:plotting/core` for an overview of how to use these functions.
+See {doc}`/tutorials/plotting/core` for an overview of how to use these functions.
 
 ```{note}
 See the {ref}`settings` section for all important plotting configurations.

docs/api/plotting.md

@@ -21,7 +21,6 @@
 
 # -- General configuration ------------------------------------------------
 
-
 nitpicky = True  # Warn about broken links. This is here for a reason: Do not change.
 needs_sphinx = "4.0"  # Nicer param docs
 suppress_warnings = [
@@ -42,6 +41,11 @@
 
 release = version
 
+# Bibliography settings
+bibtex_bibfiles = ["references.bib"]
+bibtex_reference_style = "author_year"
+
+
 # default settings
 templates_path = ["_templates"]
 master_doc = "index"
@@ -59,6 +63,7 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.autosummary",
     "sphinx.ext.extlinks",
+    "sphinxcontrib.bibtex",
     "matplotlib.sphinxext.plot_directive",
     "sphinx_autodoc_typehints",  # needs to be after napoleon
     "git_ref",  # needs to be before scanpydoc.rtd_github_links
@@ -90,7 +95,7 @@
     "html_image",
     "html_admonition",
 ]
-myst_url_schemes = ("http", "https", "mailto")
+myst_url_schemes = ("http", "https", "mailto", "ftp")
 nb_output_stderr = "remove"
 nb_execution_mode = "off"
 nb_merge_streams = True
@@ -127,7 +132,6 @@
     scipy=("https://docs.scipy.org/doc/scipy/", None),
     seaborn=("https://seaborn.pydata.org/", None),
     sklearn=("https://scikit-learn.org/stable/", None),
-    tutorials=("https://scanpy-tutorials.readthedocs.io/en/latest/", None),
 )
 
 

docs/conf.py

@@ -30,4 +30,4 @@ def cite_role(  # noqa: PLR0917
 
 
 def setup(app: Sphinx):
-    app.add_role("cite", cite_role, override=True)
+    app.add_role("cite-hack", cite_role, override=True)

docs/extensions/cite.py

@@ -0,0 +1,7 @@
+# How to
+
+This section contains short examples on how to perform specific tasks with scanpy.
+
+```{toctree}
+knn-transformers
+```

docs/how-to/index.md

@@ -0,0 +1 @@
+../../notebooks/knn-transformers.ipynb

docs/how-to/knn-transformers.ipynb

@@ -21,7 +21,7 @@ New to *scanpy*? Check out the installation guide.
 :::
 
 :::{grid-item-card} Tutorials {octicon}`play;1em;`
-:link: _tutorials
+:link: tutorials/index
 :link-type: doc
 
 The tutorials walk you through real-world applications of scanpy.
@@ -49,8 +49,9 @@ Find a bug? Interested in improving scanpy? Checkout our GitHub for the latest d
 ::::
 
 **Other resources**
+
 * Follow changes in the {ref}`release notes <release-notes>`.
-* Find tools that harmonize well with anndata & Scanpy via the {doc}`external API <external/index>` and the {doc}`ecosystem page <ecosystem>`.
+* Find tools that harmonize well with anndata & Scanpy at [scverse.org/packages/](https://scverse.org/packages/)
 * Check out our {ref}`contribution guide <contribution-guide>` for development practices.
 * Consider citing [Genome Biology (2018)] along with original {doc}`references <references>`.
 
@@ -71,9 +72,10 @@ Find a bug? Interested in improving scanpy? Checkout our GitHub for the latest d
 :hidden: true
 :maxdepth: 1
 
-_tutorials
-usage-principles
 installation
+tutorials/index
+usage-principles
+how-to/index
 api/index
 external/index
 ecosystem

docs/index.md

@@ -24,7 +24,7 @@ pip install 'scanpy[leiden]'
 ```
 
 The extra `[leiden]` installs two packages that are needed for popular
-parts of scanpy but aren't requirements: [igraph] {cite}`Csardi06` and [leiden] {cite}`Traag18`.
+parts of scanpy but aren't requirements: [igraph] {cite-hack}`Csardi06` and [leiden] {cite-hack}`Traag18`.
 
 (dev-install-instructions)=