Add notebooks to the documentation

jupyterlab · Jul 19, 2024 · d0452a7 · d0452a7
1 parent c047e5c
commit d0452a7
Show file tree

Hide file tree

Showing 16 changed files with 63 additions and 2 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -8,6 +8,8 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
+  apt_packages:
+    - pandoc
 
 sphinx:
   configuration: docs/source/conf.py

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,2 +1,4 @@
 myst_parser
 pydata_sphinx_theme
+nbsphinx
+nbsphinx-link
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -13,7 +13,7 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ["myst_parser"]
+extensions = ["myst_parser", "nbsphinx", "nbsphinx_link"]
 myst_enable_extensions = ["colon_fence"]
 
 templates_path = ["_templates"]

diff --git a/docs/source/contributors/index.md b/docs/source/contributors/index.md
@@ -95,7 +95,16 @@ refresh your browser tab.
 ## Building documentation
 
 The `./scripts/install.sh` should automatically install the documentation
-dependencies. To build the documentation locally, run
+dependencies. You will need to install [pandoc](https://pandoc.org/) as well. You can install [pandoc from the conda-forge channel](https://anaconda.org/conda-forge/pandoc):
+
+```
+conda install -c conda-forge pandoc
+```  
+
+Otherwise have a look at pandoc's [installation instructions](https://pandoc.org/installing.html).
+
+
+To build the documentation locally, run
 
 ```
 cd docs/

diff --git a/docs/source/examples/code.nblink b/docs/source/examples/code.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../../examples/code.ipynb"
+}
diff --git a/docs/source/examples/commands.nblink b/docs/source/examples/commands.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../../examples/commands.ipynb"
+}
diff --git a/docs/source/examples/errors.nblink b/docs/source/examples/errors.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../../examples/errors.ipynb"
+}
diff --git a/docs/source/examples/generate/Creating Random Arrays with Numpy.nblink b/docs/source/examples/generate/Creating Random Arrays with Numpy.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../../../examples/generate/Creating Random Arrays with Numpy.ipynb"
+}
diff --git a/docs/source/examples/generate/Introduction to Sets.nblink b/docs/source/examples/generate/Introduction to Sets.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../../../examples/generate/Introduction to Sets.ipynb"
+}
diff --git a/docs/source/examples/generate/index.md b/docs/source/examples/generate/index.md
@@ -0,0 +1,9 @@
+# Generate
+
+```{toctree}
+---
+maxdepth: 1
+---
+Creating Random Arrays with Numpy
+Introduction to Sets
+```
diff --git a/docs/source/examples/images.nblink b/docs/source/examples/images.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../../examples/images.ipynb"
+}
diff --git a/docs/source/examples/index.md b/docs/source/examples/index.md
@@ -0,0 +1,14 @@
+# Examples
+
+```{toctree}
+---
+maxdepth: 1
+---
+code
+commands
+errors
+images
+magics
+sagemaker
+generate/index
+```
diff --git a/docs/source/examples/magics.nblink b/docs/source/examples/magics.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../../examples/magics.ipynb"
+}
diff --git a/docs/source/examples/notebooks.nk b/docs/source/examples/notebooks.nk
diff --git a/docs/source/examples/sagemaker.nblink b/docs/source/examples/sagemaker.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../../examples/sagemaker.ipynb"
+}
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -35,4 +35,5 @@ maxdepth: 2
 users/index
 contributors/index
 developers/index
+examples/index
 ```