[Documentation] Adds a notebooks gallery

Signed-off-by: Alexis Jeandet <alexis.jeandet@member.fsf.org>
SciQLop · Jan 26, 2022 · f865563 · f865563
1 parent 3bf9ee1
commit f865563
Show file tree

Hide file tree

Showing 10 changed files with 571 additions and 10,759 deletions.
diff --git a/docs/_static/AMDA_nb_thumbnail.png b/docs/_static/AMDA_nb_thumbnail.png
diff --git a/docs/_static/SSCWEB_nb_thumbnail.png b/docs/_static/SSCWEB_nb_thumbnail.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -21,7 +21,9 @@
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath('..'))
+src_path = os.path.abspath('..')
+sys.path.insert(0, src_path)
+os.environ['PYTHONPATH'] = src_path
 
 # -- General configuration ---------------------------------------------
 
@@ -31,7 +33,52 @@
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'numpydoc']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
+    'sphinx_gallery.load_style',
+    'nbsphinx',
+    'numpydoc']
+
+nbsphinx_execute_arguments = [
+    "--InlineBackend.figure_formats={'svg', 'pdf'}",
+    "--InlineBackend.rc=figure.dpi=96",
+]
+
+nbsphinx_execute = 'auto'
+
+nbsphinx_thumbnails = {
+    "examples/AMDA": "_static/AMDA_nb_thumbnail.png",
+    "examples/SSCWeb": "_static/SSCWEB_nb_thumbnail.png",
+}
+
+nbsphinx_prolog = r"""
+{% set docname = 'docs/' + env.doc2path(env.docname, base=None) %}
+{% set nb_base = 'tree' if env.config.revision else 'blob' %}
+{% set nb_where = env.config.revision if env.config.revision else 'main' %}
+.. raw:: html
+    <div class="admonition note">
+      <p style="margin-bottom:0px">
+        This page was generated by
+        <a href="https://nbsphinx.readthedocs.io/">nbsphinx</a> from
+        <a class="reference external" href="https://github.com/SciQLop/speasy/{{ nb_base|e }}/{{ nb_where|e }}/{{ docname|e }}">{{ docname|e }}</a>.
+        <br>
+        Interactive online version:
+        <a href="https://mybinder.org/v2/gh/SciQLop/speasy/{{ nb_where|e }}/?filepath={{ docname|e }}"><img alt="Binder badge" src="https://mybinder.org/badge_logo.svg" style="vertical-align:text-bottom"></a>.
+      </p>
+    </div>
+.. raw:: latex
+    \nbsphinxstartnotebook{\scriptsize\noindent\strut
+    \textcolor{gray}{The following section was generated from
+    \sphinxcode{\sphinxupquote{\strut {{ docname | escape_latex }}}} \dotfill}}
+"""
+
+mathjax3_config = {
+    'tex': {'tags': 'ams', 'useLabelIds': True},
+}
+
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -95,7 +142,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # 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 = []
+html_static_path = ["_static"]
 
 # -- Options for HTMLHelp output ---------------------------------------
 

diff --git a/docs/examples/AMDA.ipynb b/docs/examples/AMDA.ipynb
diff --git a/docs/examples/SSCWeb.ipynb b/docs/examples/SSCWeb.ipynb
diff --git a/docs/examples/index.rst b/docs/examples/index.rst
@@ -0,0 +1,10 @@
+Speasy gallery
+==============
+
+Below is a gallery of examples
+
+.. nbgallery::
+   :glob:
+
+   ./AMDA
+   ./SSCWeb
diff --git a/docs/index.rst b/docs/index.rst
@@ -8,12 +8,14 @@ Space Physics made EASY
 
    installation
    user/modules
+   examples/index
    dev/index
    history
    contributing
    authors
 
 
+
 .. image:: https://matrix.to/img/matrix-badge.svg
         :target: https://matrix.to/#/#speasy:matrix.org
         :alt: Chat on Matrix

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,3 +1,5 @@
 sphinx-rtd-theme
 argh
 numpydoc
+sphinx-gallery
+nbsphinx