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

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']

  • gallery_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

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

property 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

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

Bases: docutils.parsers.rst.Directive

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

May the directive have content?

option_spec

Mapping of option names to validator functions.

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

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

property code_div

The string for creating a code example for the gallery

property 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

property 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

property reference

The rst label of this example

property 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

property supplementary_files

The supplementary files of this notebook

thumb_file

Path to the thumbnail image

property thumbnail_div

The string for creating the thumbnail of this example

property 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]

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]