Backport PR #2901: Doc submodule (#2962)

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

.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/api/plotting.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/conf.py

@@ -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/extensions/cite.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/how-to/index.md

@@ -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/knn-transformers.ipynb

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

docs/index.md

@@ -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/installation.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)=
 

docs/news.md

@@ -7,6 +7,10 @@
 
 ```
 
+### `rapids-singlecell` brings scanpy to the GPU! {small}`2024-03-18`
+
+{doc}`rapids-singlecell <rapids_singlecell:index>` by Severin Dicks provides a scanpy-like API with accelerated operations implemented on GPU.
+
 ### Scanpy hits 100 contributors! {small}`2022-03-31`
 
 [100 people have contributed to Scanpy's source code!](https://github.com/scverse/scanpy/graphs/contributors)
@@ -59,7 +63,7 @@ Bioconda, Seurat, Bioconductor, and others.
 
 ### Science “Breakthrough of the Year 2018” {small}`2018-12-01`
 
-The Science “Breakthrough of the Year 2018”, [Development cell by cell](https://vis.sciencemag.org/breakthrough2018/finalists/#cell-development), mentions the first application of PAGA {cite}`Plass18` among 5 papers.
+The Science “Breakthrough of the Year 2018”, [Development cell by cell](https://vis.sciencemag.org/breakthrough2018/finalists/#cell-development), mentions the first application of PAGA {cite-hack}`Plass18` among 5 papers.
 
 [32 projects]: https://chanzuckerberg.com/eoss/proposals/
 [essential open source software for science]: https://chanzuckerberg.com/newsroom/chan-zuckerberg-initiative-awards-5-million-for-open-source-software-projects-essential-to-science/

docs/references.bib

@@ -0,0 +1,100 @@
+@article{Wolf2018,
+  author   = {Wolf, F. Alexander
+              and Angerer, Philipp
+              and Theis, Fabian J.},
+  title    = {SCANPY: large-scale single-cell gene expression data analysis},
+  journal  = {Genome Biology},
+  year     = {2018},
+  month    = {Feb},
+  day      = {06},
+  volume   = {19},
+  number   = {1},
+  pages    = {15},
+  abstract = {Scanpy is a scalable toolkit for analyzing single-cell gene expression data. It includes methods for preprocessing, visualization, clustering, pseudotime and trajectory inference, differential expression testing, and simulation of gene regulatory networks. Its Python-based implementation efficiently deals with data sets of more than one million cells (https://github.com/theislab/Scanpy). Along with Scanpy, we present AnnData, a generic class for handling annotated data matrices (https://github.com/theislab/anndata).},
+  issn     = {1474-760X},
+  doi      = {10.1186/s13059-017-1382-0},
+  url      = {https://doi.org/10.1186/s13059-017-1382-0}
+}
+@inproceedings{luecken2021,
+  author    = {Luecken, Malte and Burkhardt, Daniel and Cannoodt, Robrecht and Lance, Christopher and Agrawal, Aditi and Aliee, Hananeh and Chen, Ann and Deconinck, Louise and Detweiler, Angela and Granados, Alejandro and Huynh, Shelly and Isacco, Laura and Kim, Yang and Klein, Dominik and DE KUMAR, BONY and Kuppasani, Sunil and Lickert, Heiko and McGeever, Aaron and Melgarejo, Joaquin and Mekonen, Honey and Morri, Maurizio and M\"{u}ller, Michaela and Neff, Norma and Paul, Sheryl and Rieck, Bastian and Schneider, Kaylie and Steelman, Scott and Sterr, Michael and Treacy, Daniel and Tong, Alexander and Villani, Alexandra-Chloe and Wang, Guilin and Yan, Jia and Zhang, Ce and Pisco, Angela and Krishnaswamy, Smita and Theis, Fabian and Bloom, Jonathan M},
+  booktitle = {Proceedings of the Neural Information Processing Systems Track on Datasets and Benchmarks},
+  editor    = {J. Vanschoren and S. Yeung},
+  pages     = {},
+  publisher = {Curran},
+  title     = {A sandbox for prediction and integration of DNA, RNA, and proteins in single cells},
+  url       = {https://datasets-benchmarks-proceedings.neurips.cc/paper_files/paper/2021/file/158f3069a435b314a80bdcb024f8e422-Paper-round2.pdf},
+  volume    = {1},
+  year      = {2021}
+}
+@article{McCarthy2017,
+  doi       = {10.1093/bioinformatics/btw777},
+  url       = {https://doi.org/10.1093/bioinformatics/btw777},
+  year      = {2017},
+  month     = jan,
+  publisher = {Oxford University Press ({OUP})},
+  volume    = {33},
+  number    = {8},
+  pages     = {1179--1186},
+  author    = {Davis J McCarthy and Kieran R Campbell and Aaron T L Lun and Quin F Wills},
+  editor    = {Ivo Hofacker},
+  title     = {Scater: pre-processing,  quality control,  normalization and visualization of single-cell {RNA}-seq data in R},
+  journal   = {Bioinformatics}
+}
+@article{Wolock2019,
+  doi       = {10.1016/j.cels.2018.11.005},
+  url       = {https://doi.org/10.1016/j.cels.2018.11.005},
+  year      = {2019},
+  month     = apr,
+  publisher = {Elsevier {BV}},
+  volume    = {8},
+  number    = {4},
+  pages     = {281--291.e9},
+  author    = {Samuel L. Wolock and Romain Lopez and Allon M. Klein},
+  title     = {Scrublet: Computational Identification of Cell Doublets in Single-Cell Transcriptomic Data},
+  journal   = {Cell Systems}
+}
+@article{Satija2015,
+  doi       = {10.1038/nbt.3192},
+  url       = {https://doi.org/10.1038/nbt.3192},
+  year      = {2015},
+  month     = apr,
+  publisher = {Springer Science and Business Media {LLC}},
+  volume    = {33},
+  number    = {5},
+  pages     = {495--502},
+  author    = {Rahul Satija and Jeffrey A Farrell and David Gennert and Alexander F Schier and Aviv Regev},
+  title     = {Spatial reconstruction of single-cell gene expression data},
+  journal   = {Nature Biotechnology}
+}
+@article{Zheng2017,
+  doi       = {10.1038/ncomms14049},
+  url       = {https://doi.org/10.1038/ncomms14049},
+  year      = {2017},
+  month     = jan,
+  publisher = {Springer Science and Business Media {LLC}},
+  volume    = {8},
+  number    = {1},
+  author    = {Grace X. Y. Zheng and Jessica M. Terry and Phillip Belgrader and Paul Ryvkin and Zachary W. Bent and Ryan Wilson and Solongo B. Ziraldo and Tobias D. Wheeler and Geoff P. McDermott and Junjie Zhu and Mark T. Gregory and Joe Shuga and Luz Montesclaros and Jason G. Underwood and Donald A. Masquelier and Stefanie Y. Nishimura and Michael Schnall-Levin and Paul W. Wyatt and Christopher M. Hindson and Rajiv Bharadwaj and Alexander Wong and Kevin D. Ness and Lan W. Beppu and H. Joachim Deeg and Christopher McFarland and Keith R. Loeb and William J. Valente and Nolan G. Ericson and Emily A. Stevens and Jerald P. Radich and Tarjei S. Mikkelsen and Benjamin J. Hindson and Jason H. Bielas},
+  title     = {Massively parallel digital transcriptional profiling of single cells},
+  journal   = {Nature Communications}
+}
+@article{stuart2019comprehensive,
+  title     = {Comprehensive integration of single-cell data},
+  author    = {Stuart, Tim and Butler, Andrew and Hoffman, Paul and Hafemeister, Christoph and Papalexi, Efthymia and Mauck, William M and Hao, Yuhan and Stoeckius, Marlon and Smibert, Peter and Satija, Rahul},
+  journal   = {Cell},
+  volume    = {177},
+  number    = {7},
+  pages     = {1888--1902},
+  year      = {2019},
+  publisher = {Elsevier}
+}
+@article{traag2019louvain,
+  title     = {From Louvain to Leiden: guaranteeing well-connected communities},
+  author    = {Traag, Vincent A and Waltman, Ludo and Van Eck, Nees Jan},
+  journal   = {Scientific reports},
+  volume    = {9},
+  number    = {1},
+  pages     = {5233},
+  year      = {2019},
+  publisher = {Nature Publishing Group UK London}
+}