Getting started¶
The module provides 2 additional configuration values.
- process_examples¶
If
True
, (the default), then the notebook files are converted to rst.
By default, the sphinx-nbexamples package converts your jupyter notebook in a
specific directory into rst files to include it into your documentation. The
process_examples
configuration value controls this conversion. If
switched off, no new files will be created.
The second configuration value, example_gallery_config
, can be used
to control which examples are converted and how. They are simply the keyword
arguments for the Gallery
class, but we will go in
more detail in the next sections. But look into the Examples for the sphinx-nbexamples package
section to see the outcome of the gallery.
Structure of the notebooks¶
You are free to format your notebooks however you want. There are only 2 important features since we convert the notebook to a single html page:
The first cell must be a Markdown cell containing a title
The first cell should include a short summary which will then be shown as the tooltip in the summary
Choosing the examples¶
The three keywords 'examples_dirs'
, 'gallery_dirs'
, and 'pattern'
can
be used to select which notebooks shall be converted. The value for
'examples_dirs'
is the path to the directory where your raw jupyter
notebooks are located. The 'gallery_dirs'
key on the other hand will point
to the directories where the converted notebooks will be. You can also provide
a list of example directories to create multiple galleries.
Finally the 'pattern'
corresponds to the filename pattern for the example
notebooks. Using the default pattern ('example_.+.ipynb'
) implies, that
all your notebooks in the 'examples_dirs'
starts with 'example_'
Preprocessing the examples or not¶
When converting the examples, the default behaviour is to process the examples
as well. This is a good possibility if you have an automatic building of the
docs (e.g. using readthedocs.org) to check that all your examples really work.
However, you might not want this for all your notebooks, because it eventually
takes a lot of time to process all the notebooks or it requires additional
libraries. Therefore you can use the 'preprocess'
and 'dont_preprocess'
keys so select which examples are processed.
Choosing the thumbnail¶
As you see in our example gallery, little thumbnails are created for each notebook. They can be chosen via
the
'code_examples'
key in theexample_gallery_config
the
'code_example'
key in the meta data of the notebookthe
'thumbnail_figures'
key in theexample_gallery_config
the key
'thumbnail_figure'
in the meta data of the notebookautomatically from the last matplotlib figure in the example notebook
Hence, if you do not specify either 'code_examples'
nor
'thumbnail_figure'
(which is the default), it looks for a matplotlib
plot in the notebook and uses this one.
Otherwise, you have the possibility to give a small code sample via the
'code_examples'
or use the 'thumbnail_figure'
. The latter can
be the path to a picture (relative to the notebook) or a number to specify
which figure of the matplotlib figures to use.
Providing supplementary files¶
Sphinx-nbexamples automatically inserts links to download the jupyter notebook and the converted python file. However, often your example requires additional data files, etc. Here, you have two possibilities:
Specify the external data in the metadata of your notebook (see the Basic example)
Specify the external data in the
'supplementary_files'
key of yourexample_gallery_config
specific for each notebook
Including a link to the nbviewer¶
If your notebooks are also published online, you can embed a link to the wonderful jupyter nbviewer in the documentation. You have multiple options here. You can either
specify the url for each notebook separately providing a mapping from notebook file to url in the
'urls'
option of theexample_gallery_config
include a url item in the metadata of your notebook that points to the url of the notebook
specify one single url in the
'urls'
option of theexample_gallery_config
that will then be extended to the corresponding notebook path. For sphinx-nbexamples, this looks like:example_gallery_config = { urls='https://github.com/Chilipp/sphinx-nbexamples/blob/master/examples', }
Including a link to the binder¶
Jupyters binderhub allows to run the example notebooks of your repository (see for example mybinder.org). If your notebooks are also published online, sphinx-nbexamples can add a badge like in the documentation.
You have multiple options here. You can either
specify the url for each notebook separately providing a mapping from notebook file to url in the
'binder_urls'
option of theexample_gallery_config
include a binder_url item in the metadata of your notebook that points to the url of the notebook where it can be run interactively
specify one single url in the
'binder_urls'
option of theexample_gallery_config
that will then be extended to the corresponding notebook path. For sphinx-nbexamples at mybinder.org, this looks like:example_gallery_config = { 'binder_url': 'https://mybinder.org/v2/gh/Chilipp/sphinx-nbexamples/master?filepath=examples', }
or for the pangeo binder:
example_gallery_config = { 'binder_url': 'https://binder.pangeo.io/v2/gh/Chilipp/sphinx-nbexamples/master?filepath=examples', }
See the binderhub service you use (e.g. mybinder.org) for how to get this url for your repository. This will, e.g. for the example_basic.ipynb notebook, translate into:
.. image:: https://mybinder.org/badge_logo.svg :target: https://mybinder.org/v2/gh/Chilipp/sphinx-nbexamples/master?filepath=examples/example_basic.ipynb
Including bokeh¶
Warning
Bokeh is not working for the latest version (see #10). PR’s welcomed!
Note that bokeh needs a special treatment, especially when using the scheme from readthedocs.org, because it requires additional style sheets and javascript files. So, if you have bokeh plots in your documentation, we recommend to
use the
bokeh.io.output_notebook()
function in your examplesdisable the preprocessing for this notebook using the
'dont_preprocess'
keywordGive the bokeh version via the
'insert_bokeh'
keyword
If you furthermore use widgets from bokeh, use the 'insert_bokeh_widgets'
keyword, too.
Note
We cannot extract a thumbnail figure for bokeh notebooks. Hence, you should provide it by yourself (see Choosing the thumbnail).
Removing cells¶
Using notebook 5.0 and nbconvert 5.3 and higher, you can also tag cells and specify them for removal in the converted rst file.
In the jupyter notebook click on
and assign a tag to the cell you want to remove. You can then use one or more of the keywords- remove_all_outputs_tags
removes all outputs
- remove_cell_tags
removes the entire cell
- remove_input_tags
removes the input and only keeps the output
- remove_single_output_tags
Removes an individual output
in the example_gallery_config
. See the Gallery
and nbconvert.preprocessors.Preprocessor
documentation for more
information.
To remove the entire cell, for example, set
example_gallery_config = {
'remove_cell_tags': ['the-tag-of-the-cell-you-want-to-remove'],
}
in the 'conf.py'
of your docs.