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 theget_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
- base_dir (str) – Path to the base example directory (see the examples_dir
parameter for the
-
urls
¶
- examples_dirs (list of str) – list containing the directories to loop through. Default:
-
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 -
has_content
¶
-
option_spec
¶
-
-
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
-
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
-
reference
¶ The rst label of this example
-
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
-
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