Restore link checking in docs (partially reverts #2220) (#2614)

scverse · Sep 7, 2023 · 9b44a8f · 9b44a8f
1 parent f1f5c57
commit 9b44a8f
Show file tree

Hide file tree

Showing 24 changed files with 42 additions and 72 deletions.
diff --git a/.gitmodules b/.gitmodules
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -2,8 +2,9 @@ version: 2
 build:
   os: ubuntu-20.04
   tools:
-    python: '3.9'
+    python: '3.11'
 sphinx:
+  fail_on_warning: true # do not change or you will be fired
   configuration: docs/conf.py
 python:
   install:
@@ -12,6 +13,3 @@ python:
     extra_requirements:
     - doc
     - leiden
-submodules:
-  include:
-     - "docs/tutorials"
diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst
@@ -13,7 +13,7 @@
    .. autosummary::
       :toctree: .
    {% for item in attributes %}
-      {% if has_attr(fullname, item) %}
+      {% if has_member(fullname, item) %}
       ~{{ fullname }}.{{ item }}
       {% endif %}
    {%- endfor %}

diff --git a/docs/_tutorials.md b/docs/_tutorials.md
@@ -2,7 +2,7 @@
 
 ## Clustering
 
-For getting started, we recommend Scanpy’s reimplementation {doc}`/tutorials/pbmc3k`
+For getting started, we recommend Scanpy’s reimplementation {doc}`tutorials:pbmc3k`
 of Seurat’s [^cite_satija15] clustering tutorial for 3k PBMCs from 10x Genomics,
 containing preprocessing, clustering and the identification of cell types via
 known marker genes.
@@ -29,17 +29,17 @@ known marker genes.
 
 ## Visualization
 
-Learn how to visually explore genes using scanpy: {doc}`/tutorials/plotting/core`
+Learn how to visually explore genes using scanpy: {doc}`tutorials:plotting/core`
 
-For advanced customization of your plots, see {doc}`/tutorials/plotting/advanced`
+For advanced customization of your plots, see {doc}`tutorials:plotting/advanced`
 
 ```{image} _static/img/stacked_violin_dotplot_matrixplot.png
 :width: 550px
 ```
 
 ## Trajectory inference
 
-Get started with the following example for hematopoiesis for data of [^cite_paul15]: {doc}`/tutorials/paga-paul15`
+Get started with the following example for hematopoiesis for data of [^cite_paul15]: {doc}`tutorials:paga-paul15`
 
 ```{image} _static/img/tutorials/paga_paul15.png
 :width: 450px
@@ -58,16 +58,16 @@ for two hematopoiesis datasets: [DPT example 1] [^cite_paul15] and [DPT example
 
 ## Integrating datasets
 
-Map labels and embeddings of reference data to new data: {doc}`/tutorials/integrating-data-using-ingest`
+Map labels and embeddings of reference data to new data: {doc}`tutorials:integrating-data-using-ingest`
 
 ```{image} https://scanpy-tutorials.readthedocs.io/en/latest/_images/integrating-data-using-ingest_21_0.png
 :width: 350px
 ```
 
 ## Spatial data
 
-- Basic analysis of spatial data: {doc}`/tutorials/spatial/basic-analysis`
-- Integrating spatial data with scRNA-seq using scanorama: {doc}`/tutorials/spatial/integration-scanorama`
+- Basic analysis of spatial data: {doc}`tutorials:spatial/basic-analysis`
+- Integrating spatial data with scRNA-seq using scanorama: {doc}`tutorials:spatial/integration-scanorama`
 
 ```{image} _static/img/spatial-basic-analysis.png
 :width: 250px
@@ -98,7 +98,7 @@ See the [cell cycle] notebook.
 
 ### Normalization with Pearson Residuals
 
-Normalization of scRNA-seq data with Pearson Residuals, from [^cite_lause21]: {doc}`/tutorials/tutorial_pearson_residuals`
+Normalization of scRNA-seq data with Pearson Residuals, from [^cite_lause21]: {doc}`tutorials:tutorial_pearson_residuals`
 
 ### Scaling Computations
 
@@ -140,18 +140,3 @@ See pseudotime-time inference on deep-learning based features for [cell cycle re
 [scanpy in r]: https://theislab.github.io/scanpy-in-R/
 [seurat to anndata]: https://github.com/LuckyMD/Code_snippets/blob/master/Seurat_to_anndata.ipynb
 [toggleswitch]: https://nbviewer.jupyter.org/github/scverse/scanpy_usage/blob/master/170430_krumsiek11/toggleswitch.ipynb
-
-
-```{toctree}
-:hidden: true
-:maxdepth: 1
-
-tutorials/pbmc3k
-tutorials/paga-paul15
-tutorials/plotting/core
-tutorials/plotting/advanced
-tutorials/integrating-data-using-ingest
-tutorials/spatial/basic-analysis
-tutorials/spatial/integration-scanorama
-tutorials/tutorial_pearson_residuals
-```
diff --git a/docs/api/plotting.md b/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 {tutorial}`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.

diff --git a/docs/conf.py b/docs/conf.py
@@ -9,6 +9,7 @@
 from typing import Any
 
 import matplotlib  # noqa
+from sphinx.application import Sphinx
 from packaging.version import parse as parse_version
 
 # Don’t use tkinter agg when importing scanpy → … → matplotlib
@@ -18,7 +19,6 @@
 sys.path[:0] = [str(HERE.parent), str(HERE / 'extensions')]
 import scanpy  # noqa
 
-on_rtd = os.environ.get('READTHEDOCS') == 'True'
 
 # -- General configuration ------------------------------------------------
 
@@ -102,8 +102,6 @@
 
 typehints_defaults = 'braces'
 
-scanpy_tutorials_url = 'https://scanpy-tutorials.readthedocs.io/en/latest/'
-
 pygments_style = "default"
 pygments_dark_style = "native"
 
@@ -124,7 +122,7 @@
     scipy=('https://docs.scipy.org/doc/scipy/', None),
     seaborn=('https://seaborn.pydata.org/', None),
     sklearn=('https://scikit-learn.org/stable/', None),
-    scanpy_tutorials=(scanpy_tutorials_url, None),
+    tutorials=('https://scanpy-tutorials.readthedocs.io/en/latest/', None),
 )
 
 
@@ -134,8 +132,6 @@
 html_theme_options = {
     "repository_url": repository_url,
     "use_repository_button": True,
-    "logo_only": True,
-    "show_toc_level": 4,  # show all levels in the sidebar
 }
 html_static_path = ['_static']
 html_css_files = ["css/override.css"]
@@ -144,12 +140,8 @@
 html_title = "scanpy"
 
 
-def setup(app):
+def setup(app: Sphinx):
     """App setup hook."""
-    # TODO: fix all warnings in a future PR
-    # Many come from the tutorials, like the workshop directory
-    # which is not included in the docs
-    #     app.warningiserror = on_rtd
     app.add_config_value(
         "recommonmark_config",
         {
@@ -269,8 +261,4 @@ def linkcode_resolve(domain, info):
 extlinks = {
     "issue": ("https://github.com/scverse/scanpy/issues/%s", "issue%s"),
     "pr": ("https://github.com/scverse/scanpy/pull/%s", "pr%s"),
-    "tutorial": (
-        "https://github.com/scverse/scanpy-tutorials/%s.ipynb",
-        "tutorial: %s",
-    ),
 }
diff --git a/docs/extensions/has_attr_test.py b/docs/extensions/has_attr_test.py
@@ -1,13 +1,15 @@
+from inspect import get_annotations
+
 from jinja2.defaults import DEFAULT_NAMESPACE
 from jinja2.utils import import_string
 from sphinx.application import Sphinx
 
 
-def has_attr(obj_path: str, attr: str) -> bool:
+def has_member(obj_path: str, attr: str) -> bool:
     # https://jinja.palletsprojects.com/en/3.0.x/api/#custom-tests
     obj = import_string(obj_path)
-    return hasattr(obj, attr)
+    return hasattr(obj, attr) or attr in get_annotations(obj)
 
 
 def setup(app: Sphinx):
-    DEFAULT_NAMESPACE["has_attr"] = has_attr
+    DEFAULT_NAMESPACE["has_member"] = has_member
diff --git a/docs/external/index.md b/docs/external/index.md
@@ -2,7 +2,7 @@
 
 
 ```{eval-rst}
-.. currentmodule:: scanpy.external
+.. module:: scanpy.external
 ```
 
 ```{warning}

diff --git a/docs/index.md b/docs/index.md
@@ -50,7 +50,7 @@ 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>` and the {doc}`ecosystem page <ecosystem>`.
+* Find tools that harmonize well with anndata & Scanpy via the {doc}`external API <external/index>` and the {doc}`ecosystem page <ecosystem>`.
 * Check out our {ref}`contributing guide <contribution-guide>` for development practices.
 * Consider citing [Genome Biology (2018)] along with original {doc}`references <references>`.
 

diff --git a/docs/release-notes/1.10.0.md b/docs/release-notes/1.10.0.md
@@ -3,15 +3,15 @@
 ```{rubric} Features
 ```
 
-* {func}`sc.pp.pca` and {func}`sc.pp.regress_out` now accept a layer argument {pr}`2588` {smaller}`S Dicks`
+* {func}`scanpy.pp.pca` and {func}`scanpy.pp.regress_out` now accept a layer argument {pr}`2588` {smaller}`S Dicks`
 
 ```{rubric} Docs
 ```
 
 ```{rubric} Bug fixes
 ```
 
-* Updated {func}`~scanpy.pp.read_visium` such that it can read spaceranger 2.0 files {smaller}`L Lehner`
+* Updated {func}`~scanpy.read_visium` such that it can read spaceranger 2.0 files {smaller}`L Lehner`
 * Fix {func}`~scanpy.pp.normalize_total` {pr}`2466` {smaller}`P Angerer`
 * Fix testing package build {pr}`2468` {smaller}`P Angerer`
 

diff --git a/docs/release-notes/1.3.1.md b/docs/release-notes/1.3.1.md
@@ -13,7 +13,7 @@
 - {func}`~scanpy.pl.heatmap` for pretty heatmaps {pr}`175` {smaller}`F Ramirez`
 - {func}`~scanpy.pl.violin` produces very compact overview figures with many panels {pr}`175` {smaller}`F Ramirez`
 
-~~~{rubric} There now is a section on imputation in {doc}`external <../external>`:
+~~~{rubric} There now is a section on imputation in {doc}`external <../external/index>`:
 ~~~
 
 - {func}`~scanpy.external.pp.magic` for imputation using data diffusion [^cite_vandijk18] {pr}`187` {smaller}`S Gigante`

diff --git a/docs/release-notes/1.4.5.md b/docs/release-notes/1.4.5.md
@@ -5,7 +5,7 @@ Please install `scanpy==1.4.5.post3` instead of `scanpy==1.4.5`.
 ```{rubric} New functionality
 ```
 
-- {func}`~scanpy.tl.ingest` maps labels and embeddings of reference data to new data {tutorial}`integrating-data-using-ingest` {pr}`651` {smaller}`S Rybakov, A Wolf`
+- {func}`~scanpy.tl.ingest` maps labels and embeddings of reference data to new data {doc}`tutorials:integrating-data-using-ingest` {pr}`651` {smaller}`S Rybakov, A Wolf`
 - {mod}`~scanpy.queries` recieved many updates including enrichment through [gprofiler] and more advanced biomart queries {pr}`467` {smaller}`I Virshup`
 - {func}`~scanpy.set_figure_params` allows setting `figsize` and accepts `facecolor='white'`, useful for working in dark mode  {smaller}`A Wolf`
 

diff --git a/docs/release-notes/1.5.0.md b/docs/release-notes/1.5.0.md
@@ -5,7 +5,7 @@ The `1.5.0` release adds a lot of new functionality, much of which takes advanta
 ```{rubric} Spatial data support
 ```
 
-- Basic analysis {tutorial}`spatial/basic-analysis` and integration with single cell data {tutorial}`spatial/integration-scanorama` {smaller}`G Palla`
+- Basic analysis {doc}`tutorials:spatial/basic-analysis` and integration with single cell data {doc}`tutorials:spatial/integration-scanorama` {smaller}`G Palla`
 - {func}`~scanpy.read_visium` read 10x Visium data {pr}`1034` {smaller}`G Palla, P Angerer, I Virshup`
 - {func}`~scanpy.datasets.visium_sge` load Visium data directly from 10x Genomics {pr}`1013` {smaller}`M Mirkazemi, G Palla, P Angerer`
 - {func}`~scanpy.pl.spatial` plot spatial data {pr}`1012` {smaller}`G Palla, P Angerer`

diff --git a/docs/release-notes/1.6.0.md b/docs/release-notes/1.6.0.md
@@ -5,7 +5,7 @@ This release includes an overhaul of {func}`~scanpy.pl.dotplot`, {func}`~scanpy.
 ~~~{rubric} Overhaul of {func}`~scanpy.pl.dotplot`, {func}`~scanpy.pl.matrixplot`, and {func}`~scanpy.pl.stacked_violin` {pr}`1210` {smaller}`F Ramirez`
 ~~~
 
-- An overhauled tutorial {tutorial}`plotting/core`.
+- An overhauled tutorial {doc}`tutorials:plotting/core`.
 
 - New plotting classes can be accessed directly (e.g., {class}`~scanpy.pl.DotPlot`) or using the `return_fig` param.
 

diff --git a/docs/release-notes/1.9.0.md b/docs/release-notes/1.9.0.md
@@ -3,7 +3,7 @@
 ```{rubric} Tutorials
 ```
 
-- New tutorial on the usage of Pearson Residuals: {tutorial}`tutorial_pearson_residuals` {smaller}`J Lause, G Palla`
+- New tutorial on the usage of Pearson Residuals: {doc}`tutorials:tutorial_pearson_residuals` {smaller}`J Lause, G Palla`
 - [Materials](https://github.com/scverse/scanpy-tutorials/tree/master/scanpy_workshop) and [recordings](https://www.youtube.com/playlist?list=PL4rcQcNPLZxWQQH7LlRBMkAo5NWuHX1e3) for Scanpy workshops by Maren Büttner
 
 ```{rubric} Experimental module

diff --git a/docs/release-notes/1.9.4.md b/docs/release-notes/1.9.4.md
@@ -8,4 +8,4 @@
 * Depend on `igraph` instead of `python-igraph` {pr}`2566` {smaller}`P Angerer`
 * {func}`~scanpy.tl.rank_genes_groups` now handles unsorted groups as intended {pr}`2589` {smaller}`S Dicks`
 * {func}`~scanpy.get.rank_genes_groups_df` now works for {func}`~scanpy.tl.rank_genes_groups` with `method="logreg"` {pr}`2601` {smaller}`S Dicks`
-* {func}`~scanpy.tl._utils._choose_representation` now works with `n_pcs` if bigger than `settings.N_PCS` {pr}`2610` {smaller}`S Dicks`
+* `scanpy.tl._utils._choose_representation` now works with `n_pcs` if bigger than `settings.N_PCS` {pr}`2610` {smaller}`S Dicks`
diff --git a/docs/release-notes/index.md b/docs/release-notes/index.md
@@ -8,6 +8,9 @@
 ```
 ## Version 1.9
 
+```{include} /release-notes/1.9.4.md
+```
+
 ```{include} /release-notes/1.9.3.md
 ```
 

diff --git a/docs/tutorials b/docs/tutorials
diff --git a/scanpy/_settings.py b/scanpy/_settings.py
@@ -80,6 +80,9 @@ class ScanpyConfig:
     Config manager for scanpy.
     """
 
+    N_PCS: int
+    """Default number of principal components to use."""
+
     def __init__(
         self,
         *,
@@ -140,7 +143,6 @@ def __init__(
         """Stores the previous memory usage."""
 
         self.N_PCS = n_pcs
-        """Default number of principal components to use."""
 
     @property
     def verbosity(self) -> Verbosity:

diff --git a/scanpy/datasets/_datasets.py b/scanpy/datasets/_datasets.py
@@ -292,7 +292,7 @@ def pbmc3k() -> ad.AnnData:
 def pbmc3k_processed() -> ad.AnnData:
     """Processed 3k PBMCs from 10x Genomics.
 
-    Processed using the `basic tutorial <https://scanpy-tutorials.readthedocs.io/en/latest/pbmc3k.html>`__.
+    Processed using the basic tutorial :doc:`tutorials:pbmc3k`.
 
     Returns
     -------

diff --git a/scanpy/neighbors/__init__.py b/scanpy/neighbors/__init__.py
@@ -25,9 +25,8 @@
 from .. import settings
 
 N_DCS = 15  # default number of diffusion components
-N_PCS = (
-    settings.N_PCS
-)  # Backwards compat, constants should be defined in only one place.
+# Backwards compat, constants should be defined in only one place.
+N_PCS = settings.N_PCS
 
 _Method = Literal['umap', 'gauss', 'rapids']
 _MetricFn = Callable[[np.ndarray, np.ndarray], float]

diff --git a/scanpy/plotting/_tools/scatterplots.py b/scanpy/plotting/_tools/scatterplots.py
@@ -983,7 +983,7 @@ def spatial(
     --------
     :func:`scanpy.datasets.visium_sge`
         Example visium data.
-    :tutorial:`spatial/basic-analysis`
+    :doc:`tutorials:spatial/basic-analysis`
         Tutorial on spatial analysis.
     """
     # get default image params if available

diff --git a/scanpy/tools/_ingest.py b/scanpy/tools/_ingest.py
@@ -34,7 +34,7 @@ def ingest(
     """\
     Map labels and embeddings from reference data to new data.
 
-    :tutorial:`integrating-data-using-ingest`
+    :doc:`tutorials:integrating-data-using-ingest`
 
     Integrates embeddings and annotations of an `adata` with a reference dataset
     `adata_ref` through projecting on a PCA (or alternate
@@ -102,9 +102,6 @@ def ingest(
     >>> sc.pp.neighbors(adata_ref)
     >>> sc.tl.umap(adata_ref)
     >>> sc.tl.ingest(adata, adata_ref, obs='cell_type')
-
-    .. _ingest PBMC tutorial: https://scanpy-tutorials.readthedocs.io/en/latest/integrating-pbmcs-using-ingest.html
-    .. _ingest Pancreas tutorial: https://scanpy-tutorials.readthedocs.io/en/latest/integrating-pancreas-using-ingest.html
     """
     # anndata version check
     anndata_version = pkg_version("anndata")

diff --git a/scanpy/tools/_utils.py b/scanpy/tools/_utils.py
@@ -10,7 +10,7 @@
 use_rep
     Use the indicated representation. `'X'` or any key for `.obsm` is valid.
     If `None`, the representation is chosen automatically:
-    For `.n_vars` < :attr:`scanpy.settings.N_PCS` (default: 50), `.X` is used, otherwise 'X_pca' is used.
+    For `.n_vars` < :attr:`~scanpy._settings.ScanpyConfig.N_PCS` (default: 50), `.X` is used, otherwise 'X_pca' is used.
     If 'X_pca' is not present, it’s computed with default parameters or `n_pcs` if present.\
 """