Read, write, and execute Jupyter Notebooks in Sphinx
MyST-NB is a reference implementation of MyST Markdown Notebooks, and
an open source tool for working with Jupyter Notebooks in the
Sphinx ecosystem. It provides the following primary features:
Parse ipynb files in Sphinx. Directly convert Jupyter Notebooks into Sphinx documents.
Execute and Cache your notebook content. Save time building your documentation without needing to commit your notebook outputs directly into
Write MyST Markdown. MyST Markdown allows you to write Sphinx roles and directives in markdown.
Insert notebook outputs into your content. Generate outputs as you build your documentation, and insert them across pages.
Write Jupyter Notebooks entirely with Markdown. You can define the structure of a notebook in pure-text making it more diff-able.
In addition, there are several options for controlling the look and feel of how your notebooks are used in your documentation. See the documentation pages to the left for more information.
This project is in a beta state. Comments, requests, or bugreports are welcome and recommended! Please open an issue here
Installation and basic usage¶
myst-nb, do the following:
myst-nbwith the following command:
pip install myst-nb
myst_nbextension in your Sphinx repository’s extensions:
extensions = [ ..., "myst_nb" ]
By default, MyST-NB will parse both markdown (
.md) and notebooks (
Write Jupyter Notebooks with your built documentation, and remember to include them in your
toctree, and that’s it!
Customize and configure¶
For information on using and configuring MyST-NB, as well as some examples of notebook outputs, see the pages below:
- Using with Sphinx
- Get started
- Write your notebook content
- Hiding cell contents
- Executing and cacheing your content
- Inserting variables into pages with
- Gluing variables in your notebook
- Pasting glued variables into your page
- Controling the pasted outputs
- Advanced glue usecases
- MyST Markdown Notebooks
In addition, here is a reference page that uses the
jupyter-sphinx package to create
outputs, to compare how these outputs look relative to the MyST-NB style.
Finally, here is documentation on contributing to the development of MySt-NB