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'
:
Boolean controlling whether the rst files shall created and examples processed |
|
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 notebooksupplementary_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 notebookother_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 notebookthumbnail_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
- property binder_urls¶
- classmethod from_sphinx(app)[source]¶
Class method to create a
Gallery
instance from the configuration of a sphinx application
- 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
- has_content¶
May the directive have content?
- option_spec¶
Mapping of option names to validator functions.
- 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 notebooksupplementary_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
- 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
andnbformat
modules. It creates theoutfile
notebook, a python and a rst file
- property reference¶
The rst label of this example
- property remove_tags¶
- 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
- gallery_config¶
dictionary containing the configuration of the example gallery.
Possible keys for the dictionary are the initialization keys of the
Gallery
class
- process_examples¶
Boolean controlling whether the rst files shall created and examples processed