Add notebooks to the documentation (jupyterlab#906)

* 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 <[email protected]>

Author: andrewfulton9

.readthedocs.yaml

@@ -8,6 +8,8 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
+  apt_packages:
+    - pandoc
 
 sphinx:
   configuration: docs/source/conf.py

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

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"]

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/

docs/source/examples/code.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../examples/code.ipynb"
+}

docs/source/examples/commands.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../examples/commands.ipynb"
+}

docs/source/examples/errors.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../examples/errors.ipynb"
+}

docs/source/examples/generate/Creating Random Arrays with Numpy.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../../examples/generate/Creating Random Arrays with Numpy.ipynb"
+}

docs/source/examples/generate/Introduction to Sets.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../../examples/generate/Introduction to Sets.ipynb"
+}

docs/source/examples/generate/index.md

@@ -0,0 +1,9 @@
+# Generate
+
+```{toctree}
+---
+maxdepth: 1
+---
+Creating Random Arrays with Numpy
+Introduction to Sets
+```

docs/source/examples/images.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../examples/images.ipynb"
+}

docs/source/examples/index.md

@@ -0,0 +1,14 @@
+# Examples
+
+```{toctree}
+---
+maxdepth: 1
+---
+code
+commands
+errors
+images
+magics
+sagemaker
+generate/index
+```

docs/source/examples/magics.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../examples/magics.ipynb"
+}

docs/source/examples/notebooks.nk

@@ -0,0 +1,3 @@
+{
+    "path": "../../../examples/sagemaker.ipynb"
+}

docs/source/examples/sagemaker.nblink

@@ -35,4 +35,5 @@ maxdepth: 2
 users/index
 contributors/index
 developers/index
+examples/index
 ```