check notebooks are in table of contents

Author: Marco Gorelli

.pre-commit-config.yaml

@@ -1,17 +1,17 @@
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v3.2.0
+  rev: v3.3.0
   hooks:
     -   id: end-of-file-fixer
     -   id: check-toml
 - repo: https://github.com/nbQA-dev/nbQA
-  rev: 0.3.2
+  rev: 0.3.5
   hooks:
     - id: nbqa-black
     - id: nbqa-isort
     - id: nbqa-pyupgrade
 - repo: https://github.com/asottile/pyupgrade
-  rev: v2.7.2
+  rev: v2.7.3
   hooks:
     - id: pyupgrade
       args: [--py36-plus]
@@ -26,3 +26,8 @@ repos:
       types: [jupyter]
       entry: python scripts/check_watermark.py
       language: python
+    - id: check-toc
+      name: Check all notebooks appear in table of contents
+      entry: python scripts/check_toc_is_complete.py
+      language: python
+      pass_filenames: false

docs/source/notebooks/table_of_contents_examples.js

@@ -34,6 +34,7 @@ Gallery.contents = {
     "gaussian_process": "Gaussian Processes",
     "conditional-autoregressive-model": "Gaussian Processes",
     "log-gaussian-cox-process":"Gaussian Processes",
+    "GP-Circular": "Gaussian Processes",
     "dependent_density_regression": "Mixture Models",
     "dp_mix": "Mixture Models",
     "gaussian-mixture-model-advi": "Mixture Models",
@@ -59,6 +60,7 @@ Gallery.contents = {
     "ODE_with_manual_gradients": "Inference in ODE models",
     "ODE_API_introduction": "Inference in ODE models",
     "probabilistic_matrix_factorization": "Case Studies",
+    "MLDA_introduction": "MCMC",
     "MLDA_simple_linear_regression": "MCMC",
     "MLDA_gravity_surveying": "MCMC",
     "MLDA_variance_reduction_linear_regression": "MCMC"

docs/source/notebooks/table_of_contents_tutorials.js

@@ -6,13 +6,15 @@ Gallery.contents = {
     "Gaussian_Processes.rst": "Basics",
     "data_container": "Basics",
     "sampling_compound_step": "Deep dives",
+    "sampling_callback": "Deep dives",
     "sampler-stats": "Deep dives",
     "Diagnosing_biased_Inference_with_Divergences": "Deep dives",
     "Advanced_usage_of_Theano_in_PyMC3.rst": "Deep dives",
     "getting_started": "Deep dives",
     "ODE_API_shapes_and_benchmarking": "Deep dives",
     "DEMetropolisZ_EfficiencyComparison": "Deep dives",
     "DEMetropolisZ_tune_drop_fraction": "Deep dives",
+    "factor_analysis": "Deep dives",
     "blackbox_external_likelihood": "How-To",
     "profiling": "How-To",
     "howto_debugging": "How-To",

scripts/check_toc_is_complete.py

@@ -0,0 +1,22 @@
+"""
+Check that given Jupyter notebooks all contain a final watermark cell to facilite reproducibility.
+
+This is intended to be used as a pre-commit hook, see `.pre-commit-config.yaml`.
+You can run it manually with `pre-commit run check-toc --all`.
+"""
+
+import json
+from pathlib import Path
+
+if __name__ == "__main__":
+    notebooks = (Path("docs") / "source/notebooks").glob("*.ipynb")
+    toc_examples = (Path("docs") / "source/notebooks/table_of_contents_examples.js").read_text()
+    toc_tutorials = (Path("docs") / "source/notebooks/table_of_contents_tutorials.js").read_text()
+    toc_keys = {
+        **json.loads(toc_examples[toc_examples.find("{") :]),
+        **json.loads(toc_tutorials[toc_tutorials.find("{") :]),
+    }.keys()
+    for notebook in notebooks:
+        assert (
+            notebook.stem in toc_keys
+        ), f"Notebook {notebook.name} not added to table of contents!"