Create an examples gallery with sphinx from Jupyter Notebooks¶

docs
tests
package
implementations

Welcome! Similarly to Oscar Najeras sphinx-gallery module, this module intends to create an example gallery for your documentation. However, we don’t use python scripts, instead we create the example gallery out of a bunch of jupyter notebooks using nbconvert.

This package can be used to

Put all the examples you prepared in different notebooks in an pictured gallery
use the same html (sphinx) scheme for your examples that you are using for your documentation
Include the example notebooks in an offline (pdf) documentation
Include not only the code, but also the link to required supplementary files
Include a link to the Jupyter nbviewer

Content¶

Installation¶

How to install¶

Installation using pip¶

If you do not want to use conda for managing your python packages, you can also use the python package manager pip and install via:

$ pip install sphinx-nbexamples

If you want to preprocess your notebooks before including them in the documentation, you might also have to install the ipykernel module via:

$ pip install ipykernel

and register the kernel depending on the kernel name in your notebooks via:

$ python -m ipykernel install --user --name <kernel-name> --display-name <kernel-name>

where the <kernel-name> should be replaced by the kernel name as it is used in the examples.

Note

If your examples require additional packages, you of course have to install them by yourself

Installation from source¶

You can as well install the package from the github via:

$ python setup.py install

Usage on readthedocs.org ¶

When building your documentation on readthedocs.org, you can either disable the preprocessing of the notebooks via the process_examples configuration value, e.g. via:

on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
process_examples = not on_rtd

or:

example_gallery_config['dont_preprocess'] = on_rtd

or you make sure that the virtual environment installs ipykernel and all the other necessary packages for your examples and include:

on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if on_rtd:
    import subprocess as spr
    spr.call([sys.executable] +
             ('-m ipykernel install --user --name python3 '
              '--display-name python3').split())

in your 'conf.py' of your sphinx documentation. Change 'python3' to the kernel name you are using in your examples.

Running the tests¶

We use pytest for our testing, so simply install it and run:

$ py.test

or in the downloaded directory from github run

$ python setup.py pytest

Building the docs¶

To build the docs, check out the github repository and install the requirements in 'docs/environment.yml'. The easiest way to do this is via anaconda by typing:

$ conda env create -f docs/environment.yml
$ source activate sphinx_nbexamples_docs
$ conda install ipykernel sphinx_rtd_theme

Then build the docs via:

$ cd docs
$ make html

Getting started¶

The module provides 2 additional configuration values.

process_examples¶: If True, (the default), then the notebook files are converted to rst.

example_gallery_config¶: A dictionary with the parameters of the Gallery class

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 the example_gallery_config
the 'code_example' key in the meta data of the notebook
the 'thumbnail_figures' key in the example_gallery_config
the key 'thumbnail_figures' in the meta data of the notebook
automatically 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 your example_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 the example_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 the example_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 the example_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 the example_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 examples
disable the preprocessing for this notebook using the 'dont_preprocess' keyword
Give 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 View ‣ Cell Toolbar ‣ Tags 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.

Linking to other galleries¶

You can insert the links to the example galleries in other projects using the linkgalleries directive. This will insert all the thumbnails and the titles of the examples in a list. You can find an example below.

.. linkgalleries::¶

Insert links to other example galleries generated with the sphinx-nbexamples extension.

The directive takes no arguments and the options are the same as for the figure directive. By default, we use a width of 160px and the align parameter is set to 'left'.

Each line of the content for this package must be the name of a package as it is registered in the intersphinx_mapping configuration value by the sphinx.ext.intersphinx extension. Optionally you can also provide the folder for the examples.

Warning

This directive only works well for examples that have a thumbnail associated with them, i.e. not with code examples (see Choosing the thumbnail).

Examples

To insert links to the examples of the sphinx-nbexamples gallery you can either use

.. linkgalleries::

    sphinx_nbexamples

or more explicit

.. linkgalleries::

    sphinx_nbexamples examples

Linked gallery example¶

The outputs of

.. linkgalleries::

    psyplot

are links to the examples in psyplots example gallery.

This then transforms to

Usage of Climate Data Operators

Applying your own post processing

Sharing formatoptions

In the conf.py script, the intersphinx_mapping configuration value then looks like

intersphinx_mapping = {
    'psyplot': ('http://psyplot.readthedocs.io/en/latest/', None),
    }

We can also insert links into the library of the current project by just inserting the name of the project.

In our case (sphinx-nbexamples) this then looks like

Bash example

Basic example

Bokeh example

The linkgalleries directive also accepts multiple packages, e.g.

.. linkgalleries::

    psyplot
    sphinx-nbexamples

Examples for the sphinx-nbexamples package¶

Those examples shall just show you how you might use the sphinx-nbexamples package. All those examples are generated automatically from the examples directory of the package. But you can also download them from the given notebook.

Bash example¶

This example notebook uses a Bash kernel.

# A basic hello, world in Bash

function hello {
    echo hello, world
}

hello

hello, world

Download bash script: example_bash.sh

Download Jupyter notebook: example_bash.ipynb

View the notebook in the Jupyter nbviewer

Run this example interactively:

Basic example¶

This example notebook demonstrates as a basic example how sphinx-nbexamples works.

You can edit the metadata of the notebook as shown in the screenshot below and include supplementary files, select an image for displaying it in the gallery or provide a code example.

Edit metadata

Otherwise you can do whatever you want. You can also include ipython magic commands, e.g %matplotlib inline

which then will be (as well as all the warnings) removed in the rendered html file of your example.

By default, the sphinx-nbexamples looks for pictures you created with matplotlib and saved it in the notebook. If such a picture exists, it uses the last created picture as a thumbnail in the gallery. For this example, we modified the the thumbnail_figure key of the notebook metadata to use our own picture (the one you see above).

import matplotlib.pyplot as plt
import numpy as np
import seaborn as sns

x = np.linspace(-np.pi, np.pi, 300)

xx, yy = np.meshgrid(x, x)
z = (np.sin(xx) + np.sin(yy)) ** 2

plt.figure()
plt.imshow(z, cmap='Greens')
plt.colorbar()

<matplotlib.colorbar.Colorbar at 0x7fac60d2f438>

Download python script: example_basic.py

Download Jupyter notebook: example_basic.ipynb

View the notebook in the Jupyter nbviewer

Run this example interactively:

Examples in a subfolder¶

Just some examples in a subfolder. Important is, that you have a README.rst file in this folder. You can also have more subfolders with examples in it.

Bokeh example¶

This example demonstrates the use of bokeh in the sphinx-nbgallery.

The example is taken from the bokeh-notebook gallery to demonstrate the use bokeh. For the sphinx-nbgallery, you have to do 3 additional modifications in the example_gallery_config of your conf.py:

You have to set the insert_bokeh configuration value because we need additional style sheets and javascript files
Note, that, since the output_notebook function needs some time, we recommend to use the dont_preprocess configuration value for this notebook.
We cannot estimate a thumbnail figure for a notebook not using matplotlib. So you should provide it using the thumbnail_figure metadata key (as it has been done for this notebook)

from bokeh.models import HoverTool, ColumnDataSource
from bokeh.palettes import Viridis6
from bokeh.plotting import figure, show, output_notebook
from bokeh.sampledata.us_counties import data as counties
from bokeh.sampledata.unemployment import data as unemployment

counties = {
    code: county for code, county in counties.items() if county["state"] == "tx"
}

county_xs = [county["lons"] for county in counties.values()]
county_ys = [county["lats"] for county in counties.values()]

county_names = [county['name'] for county in counties.values()]
county_rates = [unemployment[county_id] for county_id in counties]
county_colors = [Viridis6[int(rate/3)] for rate in county_rates]

source = ColumnDataSource(data=dict(
    x=county_xs,
    y=county_ys,
    color=county_colors,
    name=county_names,
    rate=county_rates,
))

output_notebook()

Loading BokehJS ...

TOOLS="pan,wheel_zoom,box_zoom,reset,hover,save"

p = figure(title="Texas Unemployment 2009", tools=TOOLS,
           x_axis_location=None, y_axis_location=None)
p.grid.grid_line_color = None

p.patches('x', 'y', source=source,
          fill_color='color', fill_alpha=0.7,
          line_color="white", line_width=0.5)

hover = p.select_one(HoverTool)
hover.point_policy = "follow_mouse"
hover.tooltips = [
    ("Name", "@name"),
    ("Unemployment rate)", "@rate%"),
    ("(Long, Lat)", "($x, $y)"),
]

show(p)

<Bokeh Notebook handle for In[6]>

Download python script: example_bokeh.py

Download Jupyter notebook: example_bokeh.ipynb

View the notebook in the Jupyter nbviewer

Run this example interactively:

Bokeh example

Bash example

Basic example

Examples in a subfolder

Bokeh example

API Reference¶

Create an example gallery out of a bunch of ipython notebooks

This sphinx extension extracts the ipython notebooks in a given folder to create an example gallery. It provides the follwing configuration values for you sphinx configuration file 'conf.py':

`process_examples`	Boolean controlling whether the rst files shall created and examples processed
`gallery_config`	dictionary containing the configuration of the example gallery.

Notes

This module was motivated by the sphinx-gallery module by Oscar Najera and in fact uses parts of it’s html template for including the thumbnails and the download containers

Classes

`Gallery`([examples_dirs, gallery_dirs, …])	Class to create one or more example gallerys
`LinkGalleriesDirective`(name, arguments, …)
`NotebookProcessor`(infile, outfile[, …])	Class to run process one ipython notebook and create the necessary files

Functions

`align`(argument)	Conversion function for the “align” option.
`create_dirs`(*dirs)
`isstring`(s)
`nbviewer_link`(url)	Return the link to the Jupyter nbviewer for the given notebook url
`setup`(app)

Data

`gallery_config`	dictionary containing the configuration of the example gallery.
`process_examples`	Boolean controlling whether the rst files shall created and examples

class Gallery(examples_dirs=['../examples'], gallery_dirs=None, pattern='example_.+.ipynb', disable_warnings=True, dont_preprocess=[], preprocess=True, clear=True, dont_clear=[], code_examples={}, supplementary_files={}, other_supplementary_files={}, thumbnail_figures={}, urls=None, insert_bokeh=False, insert_bokeh_widgets=False, remove_all_outputs_tags={}, remove_cell_tags={}, remove_input_tags={}, remove_single_output_tags={}, toctree_depth=-1, binder_url=None)[source]¶

Bases: object

Class to create one or more example gallerys

Parameters:

examples_dirs (list of str) – list containing the directories to loop through. Default: ['../examples']
gallerys_dirs (list of str) – None or list of directories where the rst files shall be created. If None, the current working directory and the name of the corresponding directory in the examples_dirs is used. Default: None
pattern (list of str) – str. The pattern to use to find the ipython notebooks. Default: 'example_.+.ipynb'
disable_warnings (bool) – Boolean controlling whether warnings shall be disabled when processing the examples. Default: True
preprocess (bool or list of str) – If True, all examples (except those specified in the dont_preprocess item) will be preprocessed when creating the rst files. Otherwise it might be a list of files that shall be preprocessed.
dont_preprocess (bool or list of str) – If True, no example will be preprocessed when creating the rst files. Otherwise it might be a list of files that shall not be preprocessed
clear (bool or list of str) – If True, the output in all notebooks to download will be cleared. Otherwise it might be a list of notebook files of whom to clear the output
dont_clear (bool or list of str) – If True, the output in all notebooks to download will not be cleared. Otherwise it might be a list of notebook files of whom not to clear the output
code_examples (dict) – A mapping from filename to code samples that shall be used instead of a thumbnail figure in the gallery. Note that you can also include a 'code_example' key in the metadata of the notebook
supplementary_files (dict) – A mapping from filename to a list of supplementary data files that shall copied to the documentation directory and can be downloaded. Note that you can also include a 'supplementary_files' key in the metadata of the notebook
other_supplementary_files (dict) – A mapping from filename to a list of other supplementary data files that shall copied to the documentation directory but can not be downloaded (e.g. pictures). Note that you can also include a 'other_supplementary_files' key in the metadata of the notebook
thumbnail_figures (dict) – A mapping from filename to an integer or the path of a file to use for the thumbnail
urls (str or dict) – The urls where to download the notebook. Necessary to provide a link to the jupyter nbviewer. If string, the path to the notebook will be appended for each example notebook. Otherwise it should be a dictionary with links for the given notebook
insert_bokeh (bool or str) – If True, the bokeh js [1] and the stylesheet [2] are inserted in the notebooks that have bokeh loaded (using the installed or specified bokeh version)
insert_bokeh_widgets (bool or str) – If True, the bokeh widget js [3] is inserted in the notebooks that have bokeh loaded (using the installed or specified bokeh version)
remove_all_outputs_tags (set) – Tags indicating cells for which the outputs are to be removed, matches tags in cell.metadata.tags.
remove_cell_tags (set) – Tags indicating which cells are to be removed, matches tags in cell.metadata.tags.
remove_input_tags (set) – Tags indicating cells for which input is to be removed, matches tags in cell.metadata.tags.
remove_single_output_tags (set) – Tags indicating which individual outputs are to be removed, matches output i tags in cell.outputs[i].metadata.tags.
toctree_depth (int) – Depth to expand table-of-contents trees to. To disable, set to 0. For automatic depth, set to -1. Default: -1
binder_url (str) – Link to the notebook on mybinder.org or equivalent

Attributes

`binder_urls`
`in_dir`	The input directories
`out_dir`	The output directories
`urls`

Methods

`from_sphinx`(app)	Class method to create a `Gallery` instance from the
`get_binder_url`(nbfile)	Return the url corresponding to the given notebook file
`get_url`(nbfile)	Return the url corresponding to the given notebook file
`process_directories`()	Create the rst files from the input directories in the
`recursive_processing`(base_dir, target_dir, it)	Method to recursivly process the notebooks in the base_dir

References

[1]	http://cdn.pydata.org/bokeh/release/bokeh-0.12.0.min.js

[2]	http://cdn.pydata.org/bokeh/release/bokeh-0.12.0.min.css

[3]	http://cdn.pydata.org/bokeh/release/bokeh-widgets-0.12.0.min.js

binder_urls¶

classmethod from_sphinx(app)[source]¶: Class method to create a Gallery instance from the configuration of a sphinx application

get_binder_url(nbfile)[source]¶

Return the url corresponding to the given notebook file

Parameters:	nbfile (str) – The path of the notebook relative to the corresponding :attr:`in_dir`
Returns:	The url or None if no url has been specified
Return type:	str or None

get_url(nbfile)[source]¶

Return the url corresponding to the given notebook file

Parameters:	nbfile (str) – The path of the notebook relative to the corresponding :attr:`in_dir`
Returns:	The url or None if no url has been specified
Return type:	str or None

in_dir¶: The input directories

out_dir¶: The output directories

process_directories()[source]¶: Create the rst files from the input directories in the in_dir attribute

recursive_processing(base_dir, target_dir, it)[source]¶

Method to recursivly process the notebooks in the base_dir

Parameters:	base_dir (str) – Path to the base example directory (see the examples_dir parameter for the `Gallery` class) target_dir (str) – Path to the output directory for the rst files (see the gallery_dirs parameter for the `Gallery` class) it (iterable) – The iterator over the subdirectories and files in base_dir generated by the `os.walk()` function

urls¶

class LinkGalleriesDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶

Bases: docutils.parsers.rst.Directive

Methods

`create_image_nodes`(header, thumb_url, key[, …])
`get_outdirs`()
`run`()

Attributes

`has_content`	bool(x) -> bool
`option_spec`	dict() -> new empty dictionary

create_image_nodes(header, thumb_url, key, link_url=None)[source]¶

get_outdirs()[source]¶

has_content¶

option_spec¶

run()[source]¶

class NotebookProcessor(infile, outfile, disable_warnings=True, preprocess=True, clear=True, code_example=None, supplementary_files=None, other_supplementary_files=None, thumbnail_figure=None, url=None, insert_bokeh=False, insert_bokeh_widgets=False, tag_options={}, binder_url=None)[source]¶

Bases: object

Class to run process one ipython notebook and create the necessary files

Parameters:

infile (str) – path to the existing notebook
outfile (str) – path to the new notebook
disable_warnings (bool) – Boolean to control whether warnings shall be included in the rst file or not
preprocess (bool) – If True, the notebook is processed when generating the rst file
clear (bool) – If True, the output in the download notebook is cleared
code_example (str) – A python code sample that shall be used instead of a thumbnail figure in the gallery. Note that you can also include a 'code_example' key in the metadata of the notebook
supplementary_files (list of str) – Supplementary data files that shall be copied to the output directory and inserted in the rst file for download
other_supplementary_files (list of str) – Other supplementary data files that shall be copied but not inserted for download
thumbnail_figure (int) – The number of the figure that shall be used for download or a path to a file
url (str) – The url where to download the notebook
insert_bokeh (False or str) – The version string for bokeh to use for the style sheet
insert_bokeh_widgets (bool or str) – The version string for bokeh to use for the widgets style sheet
tag_options (dict) – A dictionary with traitlets for the nbconvert.preprocessors.TagRemovePreprocessor
binder_url (str) – Link to the repository on mybinder.org or equivalent

Attributes

`BOKEH_JS`	str(object=’‘) -> str
`BOKEH_STYLE_SHEET`	str(object=’‘) -> str
`BOKEH_TEMPLATE`	str(object=’‘) -> str
`BOKEH_WIDGETS_JS`	str(object=’‘) -> str
`BOKEH_WIDGETS_STYLE_SHEET`	str(object=’‘) -> str
`BOKEH_WIDGETS_TEMPLATE`	str(object=’‘) -> str
`CODE_DOWNLOAD`	base string for downloading the python file and ipython notebook
`CODE_DOWNLOAD_NBVIEWER`	base string for viewing the notebook in the jupyter nbviewer
`CODE_RUN_BINDER`	base string for viewing the notebook in the binder
`CODE_TEMPLATE`	str(object=’‘) -> str
`DATA_DOWNLOAD`	base string for downloading supplementary data
`THUMBNAIL_TEMPLATE`	base string for creating the thumbnail
`code_div`	The string for creating a code example for the gallery
`code_example`	The code example out of the notebook metadata
`other_supplementary_files`	The supplementary files of this notebook
`pictures`	Paths to the pictures of this notebook
`reference`	The rst label of this example
`remove_tags`
`supplementary_files`	The supplementary files of this notebook
`thumb_file`	Path to the thumbnail image
`thumbnail_div`	The string for creating the thumbnail of this example
`url`	The url on jupyter nbviewer for this notebook or None if unknown

Methods

`copy_thumbnail_figure`()	The integer of the thumbnail figure
`create_py`(nb[, force])	Create the python script from the notebook node
`create_rst`(nb, in_dir, odir)	Create the rst file from the notebook node
`create_thumb`()	Create the thumbnail for html output
`data_download`(files)	Create the rst string to download supplementary data
`get_description`()	Get summary and description of this notebook
`get_out_file`([ending])	get the output file with the specified ending
`get_thumb_path`(base_dir)	Get the relative path to the thumb nail of this notebook
`process_notebook`([disable_warnings])	Process the notebook and create all the pictures and files
`save_thumbnail`(image_path)	Save the thumbnail image
`scale_image`(in_fname, out_fname, max_width, …)	Scales an image with the same aspect ratio centered in an

BOKEH_JS¶

BOKEH_STYLE_SHEET¶

BOKEH_TEMPLATE¶

BOKEH_WIDGETS_JS¶

BOKEH_WIDGETS_STYLE_SHEET¶

BOKEH_WIDGETS_TEMPLATE¶

CODE_DOWNLOAD¶: base string for downloading the python file and ipython notebook

CODE_DOWNLOAD_NBVIEWER¶: base string for viewing the notebook in the jupyter nbviewer

CODE_RUN_BINDER¶: base string for viewing the notebook in the binder

CODE_TEMPLATE¶

DATA_DOWNLOAD¶: base string for downloading supplementary data

THUMBNAIL_TEMPLATE¶: base string for creating the thumbnail

code_div¶: The string for creating a code example for the gallery

code_example¶: The code example out of the notebook metadata

copy_thumbnail_figure()[source]¶: The integer of the thumbnail figure

create_py(nb, force=False)[source]¶: Create the python script from the notebook node

create_rst(nb, in_dir, odir)[source]¶: Create the rst file from the notebook node

create_thumb()[source]¶: Create the thumbnail for html output

data_download(files)[source]¶: Create the rst string to download supplementary data

get_description()[source]¶: Get summary and description of this notebook

get_out_file(ending='rst')[source]¶: get the output file with the specified ending

get_thumb_path(base_dir)[source]¶: Get the relative path to the thumb nail of this notebook

other_supplementary_files¶: The supplementary files of this notebook

pictures¶: Paths to the pictures of this notebook

process_notebook(disable_warnings=True)[source]¶

Process the notebook and create all the pictures and files

This method runs the notebook using the nbconvert and nbformat modules. It creates the outfile notebook, a python and a rst file

reference¶: The rst label of this example

remove_tags¶

save_thumbnail(image_path)[source]¶: Save the thumbnail image

scale_image(in_fname, out_fname, max_width, max_height)[source]¶: Scales an image with the same aspect ratio centered in an image with a given max_width and max_height if in_fname == out_fname the image can only be scaled down

supplementary_files¶: The supplementary files of this notebook

thumb_file¶: Path to the thumbnail image

thumbnail_div¶: The string for creating the thumbnail of this example

url¶: The url on jupyter nbviewer for this notebook or None if unknown

align(argument)[source]¶: Conversion function for the “align” option.

create_dirs(*dirs)[source]¶

gallery_config¶

dictionary containing the configuration of the example gallery.

Possible keys for the dictionary are the initialization keys of the Gallery class

isstring(s)[source]¶

nbviewer_link(url)[source]¶: Return the link to the Jupyter nbviewer for the given notebook url

process_examples¶: Boolean controlling whether the rst files shall created and examples processed

setup(app)[source]¶

Changelog¶

v0.3.1¶

This patch fixes some minor logging issues with sphinx >1.7.6

Changed¶

Minor compatibility fix for using the logger with Sphinx
Corrected typos see PR #1

v0.3.0¶

Added¶

The removal of tags for the converted rst file. With nbconvert 5.3 we have the nbconvert.preprocessors.TagRemovePreprocessor available which gave the motivation to 4 new gallery configuration values, namely

remove_all_outputs_tags: set

Tags indicating cells for which the outputs are to be removed, matches tags in cell.metadata.tags.

remove_cell_tags: set

Tags indicating which cells are to be removed, matches tags in cell.metadata.tags.

remove_input_tags: set

Tags indicating cells for which input is to be removed, matches tags in cell.metadata.tags.

remove_single_output_tags: set

Tags indicating which individual outputs are to be removed, matches output i tags in cell.outputs[i].metadata.tags.

The tags specified by these configuration values will be removed in the rst file.

v0.2.2¶

Added¶

The linkgalleries directive now can also insert links to the current sphinx project that is build

Changed¶

the linkgalleries directive uses the styles from the example_gallery_styles.css, i.e. the same style as it is used in the processed example gallery.

v0.2.1¶

Changed¶

Minor bug fix in option_spec of LinkGalleriesDirective

v0.2.0¶

Added¶

Added changelog
Added linkgalleries directive

Changed¶

The name of a thumbnail is now reference + '_thumb.png' where reference is the section label of the rst file
Reference labels are now all lower case

Installation¶

Simply install it via pip:

$ pip install sphinx-nbexamples

Or you install it via:

$ python setup.py install

from the source on GitHub.

Requirements¶

The package requires

Sphinx>=1.3: The python library for generating automated documentation
jupyter: The jupyter framework for jupyter notebooks. sphinx-nbexamples explicitly depends on
- nbconvert: For converting jupyter notebooks to RST
- jupyter_client: For managing the kernels
- ipykernel: For installing an ipython kernel and run the notebooks

Create an examples gallery with sphinx from Jupyter Notebooks¶

Content¶

Installation¶

How to install¶

Installation using pip¶

Installation from source¶

Usage on readthedocs.org¶

Running the tests¶

Building the docs¶

Getting started¶

Structure of the notebooks¶

Choosing the examples¶

Preprocessing the examples or not¶

Choosing the thumbnail¶

Providing supplementary files¶

Including a link to the nbviewer¶

Including a link to the binder¶

Including bokeh¶

Removing cells¶

Linking to other galleries¶

Linked gallery example¶

Examples for the sphinx-nbexamples package¶

Bash example¶

Basic example¶

Examples in a subfolder¶

Bokeh example¶

API Reference¶

Changelog¶

v0.3.1¶

Changed¶

v0.3.0¶

Added¶

v0.2.2¶

Added¶

Changed¶

v0.2.1¶

Changed¶

v0.2.0¶

Added¶

Changed¶

Installation¶

Requirements¶

Indices and tables¶

Usage on readthedocs.org ¶