Merge pull request #929 from YosefLab/gallery

Sphinx Gallery for user guide

docs/_static/css/sphinx_gallery.css

@@ -0,0 +1,40 @@
+/* .sphx-glr-thumbcontainer {
+    background: none !important;
+    border: 1px solid #003262!important;
+    text-align: center !important;
+    min-height: 220px !important;
+}
+
+.sphx-glr-thumbcontainer a.internal:hover {
+    color: #003262!important;
+}
+
+p.sphx-glr-timing {
+    margin: 0 !important;
+    padding-top: 24px;
+    border-top: 1px solid #000;
+}
+
+.sphx-glr-thumbcontainer:hover {
+    box-shadow: 0 0 10px #003262!important
+}
+ */
+
+
+.sphx-glr-thumbcontainer .headerlink {
+    display: none !important;
+}
+
+div.sphx-glr-thumbcontainer span {
+    font-style: normal !important;
+}
+
+.sphx-glr-thumbcontainer a.internal {
+    padding: 140px 10px 0!important;
+}
+
+.sphx-glr-thumbcontainer .figure.align-center {
+    text-align: center;
+    margin-left: 0%;
+    transform: translate(0%);
+}

docs/conf.py

@@ -26,7 +26,6 @@
 
 import scvi  # noqa
 
-
 # -- General configuration ---------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -50,19 +49,14 @@
     "scanpydoc.autosummary_generate_imported",
     *[p.stem for p in (HERE / "extensions").glob("*.py")],
     "sphinx_copybutton",
+    "sphinx_gallery.load_style",
 ]
 
 # nbsphinx specific settings
 exclude_patterns = ["_build", "**.ipynb_checkpoints"]
 nbsphinx_execute = "never"
 
-# Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
 source_suffix = ".rst"
 
 # Generate the API documentation when building
@@ -77,37 +71,10 @@
 todo_include_todos = False
 numpydoc_show_class_members = False
 annotate_defaults = True  # scanpydoc option, look into why we need this
-nbsphinx_prolog = r"""
-.. raw:: html
-
-    <style>
-        .nbinput .prompt,
-        .nboutput .prompt {
-            display: none;
-        }
-        .nboutput .stderr{
-            display: none;
-        }
-    </style>
-
-{% set docname = env.doc2path(env.docname, base=None).split("/")[-1] %}
-
-.. raw:: html
 
-    <div class="admonition note">
-    <p class="admonition-title">Note</p>
-    <p>
-      This page was generated from
-      <a class="reference external" href="https://github.com/yoseflab/scvi-tutorials/">{{ docname|e }}</a>.
-      Interactive online version:
-      <span style="white-space: nowrap;"><a href="https://colab.research.google.com/github/yoseflab/scvi_tutorials/blob/master/{{ docname|e }}"><img alt="Colab badge" src="https://colab.research.google.com/assets/colab-badge.svg" style="vertical-align:text-bottom"></a>.</span>
-    </p>
-    </div>
-"""
 # The master toctree document.
 master_doc = "index"
 
-
 intersphinx_mapping = dict(
     anndata=("https://anndata.readthedocs.io/en/stable/", None),
     ipython=("https://ipython.readthedocs.io/en/stable/", None),
@@ -122,9 +89,6 @@
     pytorch_lightning=("https://pytorch-lightning.readthedocs.io/en/stable/", None),
     pyro=("http://docs.pyro.ai/en/stable/", None),
 )
-qualname_overrides = {
-    "scvi.data.dataset.GeneExpressionDataset": "scvi.data.GeneExpressionDataset"
-}
 
 
 # General information about the project.
@@ -164,9 +128,6 @@
 # -- Options for HTML output -------------------------------------------
 
 html_show_sourcelink = True
-# html_sidebars = {
-#     "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
-# }
 html_theme = "furo"
 
 html_context = dict(
@@ -178,10 +139,8 @@
 )
 # Set link name generated in the top bar.
 html_title = "scvi-tools"
-
 html_logo = "_static/logo.png"
 
-# Material theme options (see theme.conf for more information)
 html_theme_options = {
     "sidebar_hide_name": True,
     "light_css_variables": {
@@ -221,77 +180,53 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
-
-html_css_files = ["override.css"]
-
+html_css_files = ["css/override.css", "css/sphinx_gallery.css"]
 html_show_sphinx = False
 
 
-def setup(app):
-    # https://github.com/pradyunsg/furo/issues/49
-    app.config.pygments_dark_style = "default"
-
-
-# -- Options for HTMLHelp output ---------------------------------------
+nbsphinx_prolog = r"""
+.. raw:: html
 
-# Output file base name for HTML help builder.
-htmlhelp_basename = "scvidoc"
+    <style>
+        .nbinput .prompt,
+        .nboutput .prompt {
+            display: none;
+        }
+        .nboutput .stderr{
+            display: none;
+        }
+    </style>
 
-mathjax_config = {
-    "extensions": ["tex2jax.js"],
-    "jax": ["input/TeX", "output/HTML-CSS"],
-    "tex2jax": {
-        "inlineMath": [["$", "$"], ["\\(", "\\)"]],
-        "displayMath": [["$$", "$$"], ["\\[", "\\]"]],
-        "processEscapes": True,
-    },
-}
+{% set docname = env.doc2path(env.docname, base=None).split("/")[-1] %}
 
-# -- Options for LaTeX output ------------------------------------------
+.. raw:: html
 
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
+    <div class="admonition note">
+    <p class="admonition-title">Note</p>
+    <p>
+      This page was generated from
+      <a class="reference external" href="https://github.com/yoseflab/scvi-tutorials/">{{ docname|e }}</a>.
+      Interactive online version:
+      <span style="white-space: nowrap;"><a href="https://colab.research.google.com/github/yoseflab/scvi_tutorials/blob/master/{{ docname|e }}"><img alt="Colab badge" src="https://colab.research.google.com/assets/colab-badge.svg" style="vertical-align:text-bottom"></a>.</span>
+    </p>
+    </div>
+"""
+nbsphinx_thumbnails = {
+    "user_guide/notebooks/data_loading": "_static/tutorials/anndata.svg",
+    "user_guide/notebooks/api_overview": "_static/tutorials/overview.svg",
+    "user_guide/notebooks/linear_decoder": "_static/tutorials/ldvae.svg",
+    "user_guide/notebooks/scvi_in_R": "_static/tutorials/Rlogo.png",
+    "user_guide/notebooks/harmonization": "_static/tutorials/scvi_batch.png",
+    "user_guide/notebooks/totalVI": "_static/tutorials/totalvi_cell.svg",
+    "user_guide/notebooks/AutoZI_tutorial": "_static/tutorials/history.png",
+    "user_guide/notebooks/gimvi_tutorial": "_static/tutorials/gimvi.png",
+    "user_guide/notebooks/scarches_scvi_tools": "_static/tutorials/scarches.png",
+    "user_guide/notebooks/cite_scrna_integration_w_totalVI": "_static/tutorials/cite_scrna.png",
+    "user_guide/notebooks/scVI_DE_worm": "_static/tutorials/worm.png",
+    "user_guide/notebooks/stereoscope_public_LV": "_static/tutorials/stereoscope.png",
 }
 
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass
-# [howto, manual, or own class]).
-latex_documents = [
-    (master_doc, "scvi.tex", u"scvi Documentation", u"Romain Lopez", "manual")
-]
-
-
-# -- Options for manual page output ------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "scvi", u"scVI Documentation", [author], 1)]
-
-
-# -- Options for Texinfo output ----------------------------------------
 
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    (
-        master_doc,
-        "scvi",
-        u"scvi Documentation",
-        author,
-        "scvi",
-        "One line description of project.",
-        "Miscellaneous",
-    )
-]
+def setup(app):
+    # https://github.com/pradyunsg/furo/issues/49
+    app.config.pygments_dark_style = "default"

docs/user_guide/index.rst

@@ -16,8 +16,7 @@ To download the tutorials:
 Quick start
 -----------
 
-.. toctree::
-   :maxdepth: 1
+.. nbgallery::
 
    notebooks/api_overview
    notebooks/data_loading
@@ -27,8 +26,7 @@ Quick start
 Tutorials
 ---------
 
-.. toctree::
-   :maxdepth: 1
+.. nbgallery::
 
    notebooks/totalVI
    notebooks/harmonization
@@ -42,8 +40,7 @@ Tutorials
 Model development tutorials
 ---------------------------
 
-.. toctree::
-   :maxdepth: 1
+.. nbgallery::
 
    notebooks/module_user_guide
    notebooks/model_user_guide
@@ -52,8 +49,7 @@ Model development tutorials
 Contributed tutorials
 ---------------------
 
-.. toctree::
-   :maxdepth: 1
+.. nbgallery::
 
    notebooks/scVI_DE_worm
    notebooks/stereoscope_public_LV

pyproject.toml

@@ -64,14 +64,15 @@ scikit-learn = ">=0.21.2"
 scikit-misc = {version = ">=0.1.3", optional = true}
 sphinx = {version = ">=3.4", optional = true}
 sphinx-autodoc-typehints = {version = "*", optional = true}
+sphinx-gallery = {version = ">0.6", optional = true}
 sphinx_copybutton = {version = "*", optional = true}
 torch = ">=1.7.1"
 tqdm = ">=4.56.0"
 typing_extensions = {version = "*", python = "<3.8"}
 
 [tool.poetry.extras]
 dev = ["black", "pytest", "flake8", "codecov", "scanpy", "loompy", "jupyter", "nbformat", "nbconvert", "pre-commit", "isort"]
-docs = ["sphinx", "scanpydoc", "nbsphinx", "nbsphinx-link", "ipython", "furo", "typing_extensions", "sphinx-autodoc-typehints", "sphinx_copybutton"]
+docs = ["sphinx", "scanpydoc", "nbsphinx", "nbsphinx-link", "ipython", "furo", "typing_extensions", "sphinx-autodoc-typehints", "sphinx_copybutton", "sphinx_gallery"]
 tutorials = ["scanpy", "leidenalg", "python-igraph", "loompy", "scikit-misc"]
 
 [tool.poetry.dev-dependencies]