By default, Jupyter notebooks are stored in files with the suffix .ipynb
,
which use the JSON format for storage.
However, there are libraries available which allow storing notebooks in different formats, using different file suffixes.
To use a custom notebook format in nbsphinx
, you can specify the
nbsphinx_custom_formats
option in your conf.py
file.
You have to provide the file extension
and a conversion function that takes the contents of a file (as a string)
and returns a Jupyter notebook object.
nbsphinx_custom_formats = {
'.mysuffix': 'mylibrary.converter_function',
}
The converter function can be given as a string (recommended) or as a function object.
If a conversion function takes more than a single string argument, you can specify the function name plus a dictionary with keyword arguments which will be passed to the conversion function in addition to the file contents.
nbsphinx_custom_formats = {
'.mysuffix': ['mylibrary.converter_function', {'some_arg': 42}],
}
You can of course use multiple formats by specifying multiple conversion functions.
One example for a library which provides a custom conversion function is jupytext, which allows storing the contents of Jupyter notebooks in Markdown and R-Markdown, as well as plain Julia, Python and R files.
Since its conversion function takes more than a single string argument, we have to pass a keyword argument, e.g.:
nbsphinx_custom_formats = {
'.Rmd': ['jupytext.reads', {'fmt': 'Rmd'}],
}
This very page is an example of a notebook stored in the
py:percent
format
(see docs):
!head -20 custom-formats.pct.py
# %% [markdown] # # Custom Notebook Formats # # By default, Jupyter notebooks are stored in files with the suffix `.ipynb`, # which use the JSON format for storage. # # However, there are libraries available which allow storing notebooks # in different formats, using different file suffixes. # # To use a custom notebook format in `nbsphinx`, you can specify the # `nbsphinx_custom_formats` option in your `conf.py` file. # You have to provide the file extension # and a conversion function that takes the contents of a file (as a string) # and returns a Jupyter notebook object. # # ```python # nbsphinx_custom_formats = { # '.mysuffix': 'mylibrary.converter_function', # } # ```
Another example is this gallery example page.