Run notebooks for docs (#175)

* Run the notebooks when building the docs

* Update notebooks

* Update RTD setup

* Remove unnecessary classifiers

* Some deprecation fixes to the notebooks

.pre-commit-config.yaml

@@ -1,24 +1,29 @@
 fail_fast: true
 
 repos:
--   repo: https://github.com/pre-commit/pre-commit-hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v3.2.0
     hooks:
-    -   id: debug-statements
-    -   id: end-of-file-fixer
+      - id: debug-statements
+      - id: end-of-file-fixer
 
--   repo: https://github.com/psf/black
+  - repo: https://github.com/kynan/nbstripout
+    rev: 0.6.1
+    hooks:
+      - id: nbstripout
+
+  - repo: https://github.com/psf/black
     rev: 22.12.0
     hooks:
-    -   id: black
+      - id: black-jupyter
 
--   repo: https://github.com/astral-sh/ruff-pre-commit
+  - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.0.278
     hooks:
-    -   id: ruff
+      - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
 
--   repo: https://github.com/pre-commit/mirrors-mypy
+  - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.4.1
     hooks:
-    -   id: mypy
+      - id: mypy

.readthedocs.yaml

@@ -1,12 +1,16 @@
 version: 2
 
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
-    python: "3.9"
-  commands:
-    - pip install poetry
-    - poetry install --with docs
-    - poetry run make html --directory=docs
-    - mkdir _readthedocs/
-    - mv docs/build/html _readthedocs/ 
+    python: "3.11"
+  jobs:
+    post_create_environment:
+      - pip install poetry
+    post_install:
+      # VIRTUAL_ENV needs to be set manually for now; see
+      # https://github.com/readthedocs/readthedocs.org/issues/11150 for details.
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with docs,examples
+
+sphinx:
+  configuration: docs/source/conf.py

docs/README.md

@@ -12,3 +12,12 @@ In particular `poetry run make html` is useful, as that will build the documenta
 > Alternatively, one can run `poetry run make html --directory=docs` from the project root as well.
 
 Finally, all Sphinx-related settings are configured in `docs/source/conf.py`.
+
+## Skipping the example notebooks
+
+The example notebooks are all executed by default when building the documentation.
+This can take a long time, so it is possible to skip execution when building the documentation locally.
+To do so, simply set the `SKIP_NOTEBOOKS` environmental variable when building the documentation, like so
+```shell
+SKIP_NOTEBOOKS=1 poetry run make html --directory=docs
+```

docs/source/conf.py

@@ -1,14 +1,11 @@
 import datetime
-import glob
 import os
 import shutil
 import sys
-from pathlib import Path
 
 import tomli
 
 # -- Project information
-
 sys.path.insert(0, os.path.abspath("../../"))
 
 now = datetime.date.today()
@@ -21,36 +18,28 @@
     pyproj = tomli.load(fh)
     release = version = pyproj["tool"]["poetry"]["version"]
 
-for file in glob.iglob("../../examples/*.ipynb"):
-    path = Path(file)
-
-    print(f"Copy {path.name} into docs/source/examples/")
-    shutil.copy2(path, f"examples/{path.name}")
+print("Copying example notebooks into docs/source/examples/")
+shutil.copytree("../../examples", "examples/", dirs_exist_ok=True)
 
 # -- Autodoc
-
 autoclass_content = "class"
-
 autodoc_member_order = "bysource"
-
 autodoc_default_flags = ["members"]
 
 # -- Numpydoc
-
 numpydoc_xref_param_type = True
 numpydoc_class_members_toctree = False
 
 # -- nbsphinx
+skip_notebooks = os.getenv("SKIP_NOTEBOOKS", False)
+nbsphinx_execute = "never" if skip_notebooks else "always"
 
-nbsphinx_execute = "never"
 
 # -- General configuration
-
 extensions = [
     "sphinx.ext.duration",
     "sphinx.ext.doctest",
     "sphinx.ext.autodoc",
-    # "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
     "sphinx_rtd_theme",
     "nbsphinx",
@@ -71,7 +60,6 @@
 templates_path = ["_templates"]
 
 # -- Options for HTML output
-
 html_theme = "sphinx_rtd_theme"
 
 # -- Options for EPUB output