Add notebooks to the documentation (#906)

andrewfulton9 · dlqqq · web-flow · commit cfcb3c6df4e7 · 2024-07-22T16:31:45.000Z
* Add notebooks to the documentation * pin docutils * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --------- Co-authored-by: David L. Qiu <david@qiu.dev>
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,6 @@
+# nbsphinx-link requires older version of docutils
+docutils==0.20
 myst_parser
+nbsphinx
+nbsphinx-link
 pydata_sphinx_theme
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
 ```

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+{`
	`2`	`+ "path": "../../../examples/code.ipynb"`
	`3`	`+}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+{`
	`2`	`+ "path": "../../../examples/commands.ipynb"`
	`3`	`+}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+{`
	`2`	`+ "path": "../../../examples/errors.ipynb"`
	`3`	`+}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+{`
	`2`	`+ "path": "../../../../examples/generate/Creating Random Arrays with Numpy.ipynb"`
	`3`	`+}`