Get started¶
This section covers how to get started with the MyST-NB
Sphinx extension.
The Sphinx extension allows you to read markdown (.md
) and Jupyter Notebook (.ipynb
)
files into your Sphinx site. It also enables you to write MyST Markdown
in your pages.
Install and activate¶
To install myst-nb
, do the following:
Install
myst-nb
with the following command:pip install myst-nb
Activate the
myst_nb
extension in your Sphinx site by adding it to your list of Sphinx extensions inconf.py
:extensions = [ ..., "myst_nb" ]
Once you do this, MyST-NB will now parse both markdown (.md
), Jupyter notebooks (.ipynb
), and even text-based Notebooks (.md
) into your Sphinx site
(see also custom notebook formats).
Sphinx Error Reporting¶
For .md
files, sphinx will correctly report the line number that the error or warning is associated with:
source/path:4: (WARNING/2) Duplicate reference definition: abc
For .ipynb
files, these errors also correspond to a cell index.
To allow for this, we use a special format of line number corresponding to: <CELL_INDEX> * 10000 + LINE_NUMBER
, for example:
source/path:10004: (WARNING/2) Duplicate reference definition: abc
MyST-NB configuration options¶
The MyST-NB parser derives from the base MyST-Parser, and so all the same configuration options are available. See the MyST configuration options for the full set of options.
MyST-NB then adds some additional configuration, specific to notebooks. Firstly for execution:
Option |
Default |
Description |
---|---|---|
|
“” |
Path to jupyter_cache, see here for details. |
|
() |
Exclude certain file patterns from execution, see here for details. |
|
“auto” |
The logic for executing notebooks, see here for details. |
|
|
If |
|
|
If |
|
30 |
The maximum time (in seconds) each notebook cell is allowed to run. This can also be overridden by metadata in a notebook, see here for details. |
|
|
Show failed notebook tracebacks in stdout (in addition to writing to file). |
Then for parsing and output rendering:
Option |
Default |
Description |
---|---|---|
|
|
Define custom functions for conversion of files to notebooks, see here for details. |
|
|
Dict override for MIME type render priority, see here for details. |
|
|
Entry point pointing toward a code cell output renderer, see here for details. |
|
|
pygments lexer for rendering text outputs, see here for details. |
|
|
The top-level cell metadata key, to store render control data, see here for examples. |
|
|
One of ‘show’, ‘remove’, ‘warn’, ‘error’ or ‘severe’, see here for details. |