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)

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)

Class method to create a Gallery instance from the configuration of a sphinx application

get_binder_url(nbfile)

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)

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()

Create the rst files from the input directories in the in_dir attribute

recursive_processing(base_dir, target_dir, it)

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)

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)

get_outdirs()

has_content

option_spec

run()

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)

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()

The integer of the thumbnail figure

create_py(nb, force=False)

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='rst')

get the output file with the specified ending

get_thumb_path(base_dir)

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)

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)

Save the thumbnail image

scale_image(in_fname, out_fname, max_width, max_height)

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)

Conversion function for the “align” option.

create_dirs(*dirs)

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)

nbviewer_link(url)

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)