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

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]

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]