update docs (#700)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Laurens Lehner <laurenslehner@googlemail.com> Co-authored-by: Michal Klein <46717574+michalk8@users.noreply.github.com>
scverse · Jun 13, 2023 · 703432b · 703432b
1 parent 4530150
commit 703432b
Show file tree

Hide file tree

Showing 130 changed files with 321 additions and 484 deletions.
diff --git a/.github/workflows/deployment.yml b/.github/workflows/deployment.yml
@@ -16,11 +16,11 @@ jobs:
         if: ${{ (github.event_name == 'workflow_dispatch' && github.event.inputs.reason == 'release') || (github.event_name == 'push' && startsWith(github.ref, 'refs/tags')) }}
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v2
+            - uses: actions/checkout@v3
               with:
                   fetch-depth: 0
             - name: Set up Python 3.9
-              uses: actions/setup-python@v2
+              uses: actions/setup-python@v4
               with:
                   python-version: 3.9
 
@@ -47,7 +47,7 @@ jobs:
         needs: deploy
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v2
+            - uses: actions/checkout@v3
             - name: Extract branch name
               id: vars
               run: |

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -12,13 +12,15 @@ jobs:
     lint:
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v2
+            - uses: actions/checkout@v3
+              with:
+                  submodules: true
             - name: Set up Python 3.9
-              uses: actions/setup-python@v2
+              uses: actions/setup-python@v4
               with:
                   python-version: 3.9
 
-            - uses: actions/cache@v2
+            - uses: actions/cache@v3
               with:
                   path: ~/.cache/pre-commit
                   key: precommit-${{ env.pythonLocation }}-${{ hashFiles('**/.pre-commit-config.yaml') }}

diff --git a/.github/workflows/news.yml b/.github/workflows/news.yml
@@ -10,12 +10,12 @@ jobs:
         if: ${{ github.event.pull_request.merged }}
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v2
+            - uses: actions/checkout@v3
               with:
                   token: ${{ secrets.TOWNCRIER_TOKEN }}
                   fetch-depth: 0
             - name: Set up Python 3.9
-              uses: actions/setup-python@v2
+              uses: actions/setup-python@v4
               with:
                   python-version: 3.9
 

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -7,13 +7,13 @@ jobs:
         if: ${{ startsWith(github.ref, 'refs/heads/release/v') }}
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v2
+            - uses: actions/checkout@v3
               with:
                   token: ${{ secrets.TOWNCRIER_TOKEN }}
                   fetch-depth: 0
 
             - name: Set up Python 3.9
-              uses: actions/setup-python@v2
+              uses: actions/setup-python@v4
               with:
                   python-version: 3.9
 

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -32,9 +32,9 @@ jobs:
             PYTHON: ${{ matrix.python }}
 
         steps:
-            - uses: actions/checkout@v2
+            - uses: actions/checkout@v3
             - name: Set up Python ${{ matrix.python }}
-              uses: actions/setup-python@v2
+              uses: actions/setup-python@v4
               with:
                   python-version: ${{ matrix.python }}
 
@@ -44,7 +44,7 @@ jobs:
                   echo "::set-output name=dir::$(pip cache dir)"
 
             - name: Restore pip cache
-              uses: actions/cache@v2
+              uses: actions/cache@v3
               with:
                   path: ${{ steps.pip-cache-dir.outputs.dir }}
                   key: pip-${{ runner.os }}-${{ env.pythonLocation }}-${{ hashFiles('**/requirements.txt') }}
@@ -62,7 +62,7 @@ jobs:
 
             - name: Restore data cache
               id: data-cache
-              uses: actions/cache@v2
+              uses: actions/cache@v3
               with:
                   path: |
                       ~/.cache/squidpy/*.h5ad
@@ -76,7 +76,7 @@ jobs:
             # caching .tox is not encouraged, but since we're private and this shaves off ~1min from the step
             # if any problems occur and/or once the package is public, this can be removed
             - name: Restore tox cache
-              uses: actions/cache@v2
+              uses: actions/cache@v3
               with:
                   path: .tox
                   key: tox-${{ runner.os }}-${{ env.pythonLocation }}-${{ hashFiles('**/requirements.txt', '**/tox.ini') }}

diff --git a/.gitignore b/.gitignore
@@ -75,10 +75,9 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
-docs/source/auto_examples
-docs/source/auto_tutorials
-docs/source/gen_modules
+docs/build/
+docs/api
+docs/classes
 
 # PyBuilder
 target/

diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "docs/notebooks"]
+	path = docs/notebooks
+	url = https://github.com/scverse/squidpy_notebooks
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -1,20 +1,21 @@
 version: 2
 
+build:
+    os: ubuntu-22.04
+    tools:
+        python: "3.10"
+
 sphinx:
     builder: html
-    configuration: docs/source/conf.py
+    configuration: docs/conf.py
     fail_on_warning: false
 
-formats:
-    - htmlzip
-
-build:
-    image: testing
-
 python:
-    version: 3.9
     install:
         - method: pip
           path: .
-          extra_requirements:
-              - docs
+          extra_requirements: [docs]
+
+submodules:
+    include: [docs/notebooks]
+    recursive: true
diff --git a/.scripts/ci/download_data.py b/.scripts/ci/download_data.py
@@ -28,9 +28,8 @@ def _maybe_download_data(func_name: str, path: Path) -> Any:
 
 
 def main(args: argparse.Namespace) -> None:
-    from anndata import AnnData
-
     import squidpy as sq
+    from anndata import AnnData
 
     all_datasets = sq.datasets._dataset.__all__ + sq.datasets._image.__all__
     all_extensions = ["h5ad"] * len(sq.datasets._dataset.__all__) + ["tiff"] * len(sq.datasets._image.__all__)

diff --git a/docs/Makefile b/docs/Makefile
@@ -4,8 +4,8 @@
 # You can set these variables from the command line, and also
 # from the environment for the first two.
 SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
+SPHINXBUILD   ?= python -msphinx
+SOURCEDIR     = .
 BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".
@@ -20,10 +20,5 @@ help:
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 clean:
-	@rm -rf $(BUILDDIR)/
-	@rm -rf $(SOURCEDIR)/api/
-	@rm -rf $(SOURCEDIR)/classes
-	@rm -rf $(SOURCEDIR)/auto_tutorials/
-	@rm -rf $(SOURCEDIR)/auto_examples/
-	@rm -rf $(SOURCEDIR)/gen_modules/
-	@rm -rf $(SOURCEDIR)/external_tutorials/
+	@rm -rf "$(BUILDDIR)"
+	@rm -rf "generated"
diff --git a/docs/source/_ext/typed_returns.py → docs/_ext/typed_returns.py b/docs/source/_ext/typed_returns.py → docs/_ext/typed_returns.py
diff --git a/docs/source/_static/css/custom.css → docs/_static/css/custom.css b/docs/source/_static/css/custom.css → docs/_static/css/custom.css
diff --git a/docs/source/_static/css/dataframe.css → docs/_static/css/dataframe.css b/docs/source/_static/css/dataframe.css → docs/_static/css/dataframe.css
diff --git a/docs/source/_static/css/nbsphinx.css → docs/_static/css/nbsphinx.css b/docs/source/_static/css/nbsphinx.css → docs/_static/css/nbsphinx.css
diff --git a/docs/source/_static/css/sphinx_gallery.css → docs/_static/css/sphinx_gallery.css b/docs/source/_static/css/sphinx_gallery.css → docs/_static/css/sphinx_gallery.css
diff --git a/docs/source/_static/img/figure1.png → docs/_static/img/figure1.png b/docs/source/_static/img/figure1.png → docs/_static/img/figure1.png
diff --git a/...source/_static/img/squidpy_horizontal.png → docs/_static/img/squidpy_horizontal.png b/...source/_static/img/squidpy_horizontal.png → docs/_static/img/squidpy_horizontal.png
diff --git a/docs/source/_static/img/squidpy_vertical.png → docs/_static/img/squidpy_vertical.png b/docs/source/_static/img/squidpy_vertical.png → docs/_static/img/squidpy_vertical.png
diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst
@@ -0,0 +1,34 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+    {% block methods %}
+    {%- if methods %}
+    .. rubric:: {{ _('Methods') }}
+
+    .. autosummary::
+        :toctree: .
+    {% for item in methods %}
+    {%- if item not in ['__init__'] %}
+        ~{{ name }}.{{ item }}
+    {%- endif %}
+    {%- endfor %}
+    {%- for item in all_methods %}
+    {%- if item in ['__call__'] %}
+        ~{{ name }}.{{ item }}
+    {%- endif %}
+    {%- endfor %}
+    {%- endif %}
+    {%- endblock %}
+    {% block attributes %}
+    {%- if attributes %}
+    .. rubric:: {{ _('Attributes') }}
+
+    .. autosummary::
+        :toctree: .
+    {% for item in attributes %}
+        ~{{ name }}.{{ item }}
+    {%- endfor %}
+    {%- endif %}
+    {% endblock %}
diff --git a/docs/source/_templates/breadcrumbs.html → docs/_templates/breadcrumbs.html b/docs/source/_templates/breadcrumbs.html → docs/_templates/breadcrumbs.html
diff --git a/docs/source/api.rst → docs/api.rst b/docs/source/api.rst → docs/api.rst
@@ -1,6 +1,5 @@
 API
 ===
-
 Import Squidpy as::
 
     import squidpy as sq

diff --git a/docs/source/classes.rst → docs/classes.rst b/docs/source/classes.rst → docs/classes.rst
diff --git a/docs/source/conf.py → docs/conf.py b/docs/source/conf.py → docs/conf.py
@@ -8,39 +8,49 @@
 import os
 import sys
 from datetime import datetime
+
+# from importlib.metadata import metadata
 from pathlib import Path
 
 from sphinx.application import Sphinx
-from sphinx_gallery.gen_gallery import DEFAULT_GALLERY_CONF
 
 HERE = Path(__file__).parent
-sys.path.insert(0, str(HERE.parent.parent))  # this way, we don't have to install squidpy
-sys.path.insert(0, os.path.abspath("_ext"))
+# sys.path.insert(0, str(HERE.parent.parent))  # this way, we don't have to install squidpy
+# sys.path.insert(0, os.path.abspath("_ext"))
+
+sys.path.insert(0, str(HERE / "_ext"))
+
+# -- Project information -----------------------------------------------------
 
 import squidpy  # noqa: E402
-from docs.source.utils import (  # noqa: E402
-    MaybeMiniGallery,
-    _fetch_notebooks,
-    _get_thumbnails,
-)
 
-needs_sphinx = "4.0"
+sys.path.insert(0, str(Path(__file__).parent / "_ext"))
 
 # -- Project information -----------------------------------------------------
 
-project = "Squidpy"
+project = squidpy.__name__
 author = squidpy.__author__
-copyright = f"{datetime.now():%Y}, {author}"  # noqa: A001
+version = squidpy.__version__
+copyright = f"{datetime.now():%Y}, scverse"
+
+# info = metadata("squidpy")
+# project_name = info["Name"]
+# author = info["Author"]
+# copyright = f"{datetime.now():%Y}, {author}."
+# version = info["Version"]
+# release = info["Version"]
+
+# # project = squidpy.__name__
+# # author = squidpy.__author__
+# # copyright = f"{datetime.now():%Y}, {author}"  # noqa: A001
 
-github_org = "scverse"
-github_repo = "squidpy"
-github_ref = "main"
-github_nb_repo = "squidpy_notebooks"
-_fetch_notebooks(repo_url=f"https://github.com/{github_org}/{github_nb_repo}")
+# github_org = "scverse"
+# github_repo = "squidpy"
+# github_ref = "main"
 
-# The full version, including alpha/beta/rc tags
-release = github_ref
-version = f"{release} ({squidpy.__version__})"
+# # The full version, including alpha/beta/rc tags
+# # release = github_ref
+# # version = f"{release} ({squidpy.__version__})"
 
 # -- General configuration ---------------------------------------------------
 
@@ -54,9 +64,11 @@
     "sphinx_autodoc_typehints",
     "sphinx.ext.intersphinx",
     "sphinx.ext.autosummary",
-    "sphinx_gallery.load_style",
-    "nbsphinx",
+    "sphinx.ext.mathjax",
     "sphinxcontrib.bibtex",
+    "sphinx_copybutton",
+    "myst_nb",
+    "nbsphinx",
     "typed_returns",
     "IPython.sphinxext.ipython_console_highlighting",
 ]
@@ -83,20 +95,28 @@
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
-source_suffix = [".rst", ".ipynb"]
+source_suffix = {".rst": "restructuredtext", ".ipynb": "myst-nb"}
 master_doc = "index"
 pygments_style = "sphinx"
 
+# myst
+nb_execution_mode = "off"
+myst_enable_extensions = [
+    "colon_fence",
+    "dollarmath",
+    "amsmath",
+]
+myst_heading_anchors = 2
+
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = [
-    "auto_*/**.ipynb",
-    "auto_*/**.md5",
-    "auto_*/**.py",
-    "auto_*/**/index.rst",
+    "notebooks/README.rst",
+    "notebooks/CONTRIBUTING.rst",
     "release/changelog/*",
     "**.ipynb_checkpoints",
+    "build",
 ]
 suppress_warnings = ["download.not_readable", "git.too_shallow"]
 
@@ -142,6 +162,7 @@
     "https://doi.org/10.1126/science.aau5324",
     "https://doi.org/10.1093/bioinformatics/btab164",
     "https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2716260/",
+    "https://raw.githubusercontent.com/scverse/squidpy/main/docs/_static/img/figure1.png",
 ]
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -153,35 +174,8 @@
 html_theme_options = {"navigation_depth": 4, "logo_only": True}
 html_show_sphinx = False
 
-nbsphinx_thumbnails = {**_get_thumbnails("auto_tutorials"), **_get_thumbnails("auto_examples")}
-nbsphinx_execute_arguments = [
-    "--InlineBackend.figure_formats={'png', 'pdf'}",  # correct figure resize
-    "--InlineBackend.rc={'figure.dpi': 96}",
-]
-nbsphinx_prolog = r"""
-{% set docname = 'docs/source/' + env.doc2path(env.docname, base=None) %}
-.. raw:: html
-
-    <div class="binder-badge docutils container">
-        <a class="reference external image-reference"
-           href="https://mybinder.org/v2/gh/scverse/squidpy_notebooks/{{ env.config.release|e }}?filepath={{ docname|e }}">
-        <img alt="Launch binder" src="https://mybinder.org/badge_logo.svg" width="150px">
-        </a>
-    </div>
-"""  # noqa: E501
-
 
 def setup(app: Sphinx) -> None:
-    DEFAULT_GALLERY_CONF["src_dir"] = str(HERE)
-    DEFAULT_GALLERY_CONF["backreferences_dir"] = "gen_modules/backreferences"
-    DEFAULT_GALLERY_CONF["download_all_examples"] = False
-    DEFAULT_GALLERY_CONF["show_signature"] = False
-    DEFAULT_GALLERY_CONF["log_level"] = {"backreference_missing": "info"}
-    DEFAULT_GALLERY_CONF["gallery_dirs"] = ["auto_examples", "auto_tutorials"]
-    DEFAULT_GALLERY_CONF["default_thumb_file"] = "docs/source/_static/img/squidpy_vertical.png"
-
-    app.add_config_value("sphinx_gallery_conf", DEFAULT_GALLERY_CONF, "html")
-    app.add_directive("minigallery", MaybeMiniGallery)
     app.add_css_file("css/custom.css")
     app.add_css_file("css/sphinx_gallery.css")
     app.add_css_file("css/nbsphinx.css")