Placeholder directory for pre-executed notebooks. (#473)

Author: delucchi-cmu

python-project-template/.pre-commit-config.yaml.jinja

@@ -16,6 +16,7 @@ repos:
         name: Clear output from Jupyter notebooks
         description: Clear output from Jupyter notebooks.
         files: \.ipynb$
+        exclude: ^docs/pre_executed
         stages: [commit]
         language: system
         entry: jupyter nbconvert --clear-output

python-project-template/{% if include_docs %}docs{% endif %}/notebooks/README.md

@@ -1 +1,13 @@
-Put your Jupyter notebooks here :)
+# Jupyter notebooks to run on-demand.
+
+Jupyter notebooks in this directory will be run each time you render your documentation.
+
+This means they should be able to be run with the resources in the repo, and in various environments:
+
+- any other developer's machine
+- github CI runners
+- ReadTheDocs doc generation
+
+This is great for notebooks that can run in a few minutes, on smaller datasets.
+
+For notebooks that require large datasets, access to third party APIs, large CPU or GPU requirements, put them in `./pre_executed` instead.

python-project-template/{% if include_docs %}docs{% endif %}/pre_executed/README.md

@@ -0,0 +1,16 @@
+# Pre-executed Jupyter notebooks 
+
+Jupyter notebooks in this directory will NOT be run in the docs workflows, and will be rendered with 
+the provided output cells as-is.
+
+This is useful for notebooks that require large datasets, access to third party APIs, large CPU or GPU requirements.
+
+Where possible, instead write smaller notebooks that can be run as part of a github worker, and within the ReadTheDocs rendering process.
+
+To ensure that the notebooks are not run by the notebook conversion process, you can add the following metadata block to the notebook:
+
+```
+   "nbsphinx": {
+    "execute": "never"
+   },
+```