From 385bb5ad2283a9ddcbcafb6c6377a240a5d04b59 Mon Sep 17 00:00:00 2001 From: Isaac Virshup Date: Fri, 2 Dec 2022 17:36:48 +0100 Subject: [PATCH] Add git submodule for tutorials (#852) * turn off warn as error so we can look at docs while changing * add submodule for notebooks * Add submodule commands to readthedocs * Change theme? * Revert "Change theme?" This reverts commit ec87af2fb9584eec2a361b755ce9057e89119066. * Fix syntax highlighting in notebooks * Capitalization? * Add extension, ignore other files from tutorial repo * Remove github links custom extension * Turn warningiserror back on * Fix up text on tutorials landing page --- .gitmodules | 3 ++ .readthedocs.yml | 4 +++ docs/conf.py | 12 ++++++-- docs/extensions/github_links.py | 50 --------------------------------- docs/index.rst | 2 +- docs/release-notes/0.6.0.rst | 22 +++++++-------- docs/release-notes/0.9.0.rst | 2 +- docs/tutorials.rst | 10 ------- docs/tutorials/index.rst | 14 +++++++++ docs/tutorials/notebooks | 1 + pyproject.toml | 1 + 11 files changed, 46 insertions(+), 75 deletions(-) create mode 100644 .gitmodules delete mode 100644 docs/extensions/github_links.py delete mode 100644 docs/tutorials.rst create mode 100644 docs/tutorials/index.rst create mode 160000 docs/tutorials/notebooks diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 000000000..78ec4b3e3 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "docs/tutorials/notebooks"] + path = docs/tutorials/notebooks + url = https://github.com/scverse/anndata-tutorials diff --git a/.readthedocs.yml b/.readthedocs.yml index bc9067611..f3231a5ce 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -11,3 +11,7 @@ python: path: . extra_requirements: - doc +submodules: + include: + - "docs/tutorials/notebooks" + recursive: true \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 5758a4fb2..f41290e88 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -34,7 +34,13 @@ source_suffix = ".rst" master_doc = "index" default_role = "literal" -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +exclude_patterns = [ + "_build", + "Thumbs.db", + ".DS_Store", + "**.ipynb_checkpoints", + "tutorials/notebooks/*.rst", +] pygments_style = "sphinx" extensions = [ @@ -46,14 +52,16 @@ "sphinx.ext.napoleon", "sphinx.ext.autosummary", "sphinx_autodoc_typehints", # needs to be after napoleon + "sphinx_issues", "scanpydoc", "nbsphinx", - *[p.stem for p in (HERE / "extensions").glob("*.py")], + "IPython.sphinxext.ipython_console_highlighting", ] # Generate the API documentation when building autosummary_generate = True autodoc_member_order = "bysource" +issues_github_path = "scverse/anndata" # autodoc_default_flags = ['members'] napoleon_google_docstring = False napoleon_numpy_docstring = True diff --git a/docs/extensions/github_links.py b/docs/extensions/github_links.py deleted file mode 100644 index 224edf1fe..000000000 --- a/docs/extensions/github_links.py +++ /dev/null @@ -1,50 +0,0 @@ -from types import MappingProxyType -from typing import Any, Mapping, Sequence, NamedTuple - -from docutils import nodes -from docutils.parsers.rst.directives import class_option -from docutils.parsers.rst.states import Inliner -from sphinx.application import Sphinx -from sphinx.config import Config - - -class AutoLink(NamedTuple): - class_name: str - url_template: str - title_template: str = "{}" - options: Mapping[str, Any] = MappingProxyType({"class": class_option}) - - def __call__( - self, - name: str, - rawtext: str, - text: str, - lineno: int, - inliner: Inliner, - options: Mapping[str, Any] = MappingProxyType({}), - content: Sequence[str] = (), - ): - url = self.url_template.format(text) - title = self.title_template.format(text) - options = {**dict(classes=[self.class_name]), **options} - node = nodes.reference(rawtext, title, refuri=url, **options) - return [node], [] - - -def register_links(app: Sphinx, config: Config): - gh_url = "https://github.com/{github_user}/{github_repo}".format_map( - config.html_context - ) - app.add_role("pr", AutoLink("pr", f"{gh_url}/pull/{{}}", "PR {}")) - app.add_role("issue", AutoLink("issue", f"{gh_url}/issues/{{}}", "issue {}")) - app.add_role("noteversion", AutoLink("noteversion", f"{gh_url}/releases/tag/{{}}")) - # tutorial links - tutorials_url = "https://anndata-tutorials.readthedocs.io/en/latest/" - app.add_role( - "tutorial", - AutoLink("tutorial", f"{tutorials_url}{{}}.html", "→ tutorial: {}"), - ) - - -def setup(app: Sphinx): - app.connect("config-inited", register_links) diff --git a/docs/index.rst b/docs/index.rst index e4b7922ca..ba65ee004 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -25,7 +25,7 @@ Latest additions :maxdepth: 1 :hidden: - tutorials + tutorials/index api concatenation fileformat-prose diff --git a/docs/release-notes/0.6.0.rst b/docs/release-notes/0.6.0.rst index 7c3a22887..ef0c332f1 100644 --- a/docs/release-notes/0.6.0.rst +++ b/docs/release-notes/0.6.0.rst @@ -2,27 +2,27 @@ ~~~~~~~~~~~~~~~~~~~~~~~~~ - better support for aligned mappings (obsm, varm, layers) - :noteversion:`0.6.22` :pr:`155` :smaller:`I Virshup` + `0.6.22` :pr:`155` :smaller:`I Virshup` - convenience accesors :func:`~anndata.AnnData.obs_vector`, :func:`~anndata.AnnData.var_vector` for 1d arrays. - :noteversion:`0.6.21` :pr:`144` :smaller:`I Virshup` + `0.6.21` :pr:`144` :smaller:`I Virshup` - compatibility with Scipy >=1.3 by removing `IndexMixin` dependency. - :noteversion:`0.6.20` :pr:`151` :smaller:`P Angerer` + `0.6.20` :pr:`151` :smaller:`P Angerer` - bug fix for second-indexing into views. - :noteversion:`0.6.19` :smaller:`P Angerer` + `0.6.19` :smaller:`P Angerer` - bug fix for reading excel files. - :noteversion:`0.6.19` :smaller:`A Wolf` + `0.6.19` :smaller:`A Wolf` - changed default compression to `None` in :func:`~anndata.AnnData.write_h5ad` to speed up read and write, disk space use is usually less critical. - :noteversion:`0.6.16` :smaller:`A Wolf` + `0.6.16` :smaller:`A Wolf` - maintain dtype upon copy. - :noteversion:`0.6.13` :smaller:`A Wolf` + `0.6.13` :smaller:`A Wolf` - :attr:`~anndata.AnnData.layers` inspired by `.loom `_ files allows their information lossless reading via :func:`~anndata.read_loom`. - :noteversion:`0.6.7`–:noteversion:`0.6.9` :pr:`46` & :pr:`48` :smaller:`S Rybakov` + `0.6.7`–`0.6.9` :pr:`46` & :pr:`48` :smaller:`S Rybakov` - support for reading zarr files: :func:`~anndata.read_zarr` - :noteversion:`0.6.7` :pr:`38` :smaller:`T White` + `0.6.7` :pr:`38` :smaller:`T White` - initialization from pandas DataFrames - :noteversion:`0.6.` :smaller:`A Wolf` + `0.6.` :smaller:`A Wolf` - iteration over chunks :func:`~anndata.AnnData.chunked_X` and :func:`~anndata.AnnData.chunk_X` - :noteversion:`0.6.1` :pr:`20` :smaller:`S Rybakov` + `0.6.1` :pr:`20` :smaller:`S Rybakov` 0.6.0 :small:`1 May, 2018` ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/release-notes/0.9.0.rst b/docs/release-notes/0.9.0.rst index 7534832c4..9deef7162 100644 --- a/docs/release-notes/0.9.0.rst +++ b/docs/release-notes/0.9.0.rst @@ -20,4 +20,4 @@ .. rubric:: Deprecations * :meth:`AnnData.concatenate() ` is now deprecated in favour of :func:`anndata.concat` :pr:`845` :smaller:`ivirshup` -* Previously deprecated `force_dense` arugment :meth:`AnnData.write_h5ad() ` has been removed.:pr:`855` :smaller:`ivirshup` +* Previously deprecated `force_dense` arugment :meth:`AnnData.write_h5ad() ` has been removed. :pr:`855` :smaller:`ivirshup` diff --git a/docs/tutorials.rst b/docs/tutorials.rst deleted file mode 100644 index a1b32e592..000000000 --- a/docs/tutorials.rst +++ /dev/null @@ -1,10 +0,0 @@ -Tutorials -========= - -For a quick introduction to `AnnData`, check out :tutorial:`getting-started`. - -For working with the experimental data loaders (see :ref:`experimental_api`): - -* For an example of working with pytorch :tutorial:`annloader` -* For lazily concatenating multiple files :tutorial:`anncollection` -* For interfacing pytorch models with lazy collections :tutorial:`anncollection-annloader` diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst new file mode 100644 index 000000000..181474997 --- /dev/null +++ b/docs/tutorials/index.rst @@ -0,0 +1,14 @@ +Tutorials +========= + +For a quick introduction to `AnnData`, check out :doc:`Getting Started with AnnData `. + +For working with the experimental data loaders also see :ref:`experimental_api`. + +.. toctree:: + :maxdepth: 1 + + notebooks/getting-started + notebooks/annloader + notebooks/anncollection + notebooks/anncollection-annloader \ No newline at end of file diff --git a/docs/tutorials/notebooks b/docs/tutorials/notebooks new file mode 160000 index 000000000..6778cf2e5 --- /dev/null +++ b/docs/tutorials/notebooks @@ -0,0 +1 @@ +Subproject commit 6778cf2e53a20d6684d679bacc0f51d9b63e87e6 diff --git a/pyproject.toml b/pyproject.toml index b89434415..cb5c60b79 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -71,6 +71,7 @@ doc = [ "nbsphinx", "scanpydoc>=0.7.7", "zarr", + "IPython", # For syntax highlighting in notebooks ] test = [ "loompy>=3.0.5",