Uses the myst-nb extension to generate a static site from the Jupyter notebooks using sphinx. The notebooks are executed (by default - this behavior can be toggled) before conversion, so I had to make a few changes to get all of the notebooks back into a runnable state. The majority of the changes to the notebooks themselves are:
Removed deprecated code and python2 stuff to get everything running with NX v.2.5
Added a top-level (#) title to each notebook that didn't already have one
Cleared all outputs so that the notebooks in the repo are "clean".
All sphinx-related website stuff lives in the site/ directory. I also moved all of the original notebooks themselves into a directory called notebooks as it was much easier to link to them via sphinx that way.
Since the notebooks are executed as part of the sphinx-build process, it is very easy to "test" them (i.e. ensure that they run without any [unexpected] exceptions) as part of a doc-building CI step. I've used this approach before (see e.g. https://github.com/rossbar/sample_notebook_tutorials_site) and would set it up here as well if we decide to go this direction.
Example of what the rendered site looks like: https://rossbar.github.io/notebooks-1/. I chose the sphinx_rtd_theme for consistency with the theming of the main NX documentation, but it can be changed.
Finally, note that a lot of things can be tweaked and improved (adding descriptions, better toc organization, adding binder badges to the pages, etc.). This is only a minimal example to take the existing notebooks and turn them into a sphinx site.
Uses the myst-nb extension to generate a static site from the Jupyter notebooks using sphinx. The notebooks are executed (by default - this behavior can be toggled) before conversion, so I had to make a few changes to get all of the notebooks back into a runnable state. The majority of the changes to the notebooks themselves are:
#) title to each notebook that didn't already have oneAll sphinx-related website stuff lives in the
site/directory. I also moved all of the original notebooks themselves into a directory callednotebooksas it was much easier to link to them via sphinx that way.Since the notebooks are executed as part of the sphinx-build process, it is very easy to "test" them (i.e. ensure that they run without any [unexpected] exceptions) as part of a doc-building CI step. I've used this approach before (see e.g. https://github.com/rossbar/sample_notebook_tutorials_site) and would set it up here as well if we decide to go this direction.
Example of what the rendered site looks like: https://rossbar.github.io/notebooks-1/. I chose the
sphinx_rtd_themefor consistency with the theming of the main NX documentation, but it can be changed.Finally, note that a lot of things can be tweaked and improved (adding descriptions, better toc organization, adding binder badges to the pages, etc.). This is only a minimal example to take the existing notebooks and turn them into a sphinx site.