Port examples to sphinx_gallery

Author: PicoCentauri

.github/workflows/lint.yml

@@ -27,7 +27,9 @@ jobs:
         run: |
           # ignore formatting, it will be checked by black
           export FORMATTING_RULES="E101,E111,E114,E115,E116,E117,E12,E13,E2,E3,E401,E5,E70,W1,W2,W3,W5"
-          flake8 --ignore=$FORMATTING_RULES .
+          # D205 and D400 are incompatible with the requirements of sphinx-gallery
+          export PER_FILE_IGNORES="examples/*:D205,D400"
+          flake8 --ignore=$FORMATTING_RULES --per-file-ignores=$PER_FILE_IGNORES .
       - name: Lint with black
         run: |
           black --check .

.gitignore

@@ -8,4 +8,4 @@ __pycache__
 .tox/
 build/
 dist/
-docs/source/read-only-examples
+docs/source/examples

docs/requirements.txt

@@ -1,12 +1,5 @@
-ipykernel
 matplotlib
-nbsphinx==0.8.12
-nbconvert
-numpy
-scikit-learn >=0.24.0
+pandas
 sphinx >=3.3
 sphinx_rtd_theme
-tqdm
-traitlets>=5.0
-jinja2 < 3.1
-pandas
+sphinx-gallery

docs/source/conf.py

@@ -13,46 +13,10 @@
 import os
 import sys
 import sphinx_rtd_theme
-from nbconvert import NotebookExporter
-from traitlets.config import Config
 
 ROOT = os.path.abspath(os.path.join("..", ".."))
 sys.path.insert(0, ROOT)
 
-# Copying and Compiling of Examples
-if not os.path.exists(os.path.join(ROOT, "docs/source/read-only-examples")):
-    os.mkdir(os.path.join(ROOT, "docs/source/read-only-examples"))
-
-# Set up nbconvert configuration to strip empty cells and tables of contents
-c = Config()
-c.NotebookExporter.preprocessors = [
-    "nbconvert.preprocessors.RegexRemovePreprocessor",
-    "nbconvert.preprocessors.ExecutePreprocessor",
-]
-
-# Remove any cells containing lines with the phrase "Table of Contents" or
-# consist solely of whitespace
-c.RegexRemovePreprocessor.enabled = True
-c.RegexRemovePreprocessor.patterns = [".*Table of Contents.*", "\\s*\\Z"]
-
-# Execute each notebook in a python3 kernel to make sure the content is there
-c.ExecutePreprocessor.enabled = True
-c.ExecutePreprocessor.kernel = "python3"
-
-exporter = NotebookExporter(config=c)
-
-for nb in os.listdir(os.path.join(ROOT, "examples")):
-    # Skip any non-notebooks
-    if nb.endswith("ipynb") and "no-doc" not in nb:
-        nb_in = os.path.join(ROOT, "examples", nb)
-        nb_out = os.path.join(ROOT, "docs/source/read-only-examples", nb)
-
-        # Skip any notebooks which already exist
-        if not os.path.exists(nb_out):
-            with open(nb_out, "w") as out_stream:
-                converted = exporter.from_filename(nb_in)[0]
-                out_stream.write(converted)
-
 import skmatter  # noqa
 
 # -- Project information -----------------------------------------------------
@@ -76,10 +40,33 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
-    "nbsphinx",
+    "sphinx_gallery.gen_gallery",
+    "sphinx.ext.intersphinx",
 ]
 
-nbsphinx_execute = "never"
+sphinx_gallery_conf = {
+    "filename_pattern": "/*",
+    "examples_dirs": ["../../examples"],
+    "gallery_dirs": ["examples"],
+    "min_reported_time": 60,
+    # Make the code snippet for own functions clickable
+    "reference_url": {"skmatter": None},
+}
+
+# Configuration for intersphinx: refer to the Python standard library
+# and other packages
+intersphinx_mapping = {
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "python": ("https://docs.python.org/3/", None),
+    "sklearn": (
+        "http://scikit-learn.org/stable",
+        (None, "./_intersphinx/sklearn-objects.inv"),
+    ),
+    "pandas": ("https://pandas.pydata.org/docs/", None),
+}
+
 
 # If set to False return type and description are put into one paragraph
 napoleon_use_rtype = False

docs/source/index.rst

@@ -26,6 +26,6 @@ decomposition, and selection of features and samples.
   intro
   installation
   reference
-  tutorials
+  examples/index
   contributing
   bibliography

docs/source/intro.rst

@@ -1,5 +1,5 @@
 What's in scikit-matter?
-=======================
+========================
 
 ``scikit-matter`` is a collection of `scikit-learn <https://scikit.org/>`_
 compatible utilities that implement methods born out of the materials science