sphinx_gallery.gen_gallery#

Sphinx-Gallery Generator.

Attaches Sphinx-Gallery to Sphinx in order to generate the galleries when building the documentation.

Functions#

sphinx_gallery.gen_gallery.clean_api_usage_files(app, exception)[source]#

Remove api usage .dot files.

To connect to ‘build-finished’ event.

sphinx_gallery.gen_gallery.fill_gallery_conf_defaults(app, config, check_keys=True)[source]#

Check the sphinx-gallery config and set its defaults.

This is called early at config-inited, so that all the rest of the code can do things like sphinx_gallery_conf['binder']['use_jupyter_lab'], even if the keys have not been set explicitly in conf.py.

sphinx_gallery.gen_gallery.generate_gallery_rst(app)[source]#

Generate the Main examples gallery reStructuredText.

Fill Sphinx-Gallery configuration and scan example directories (up to one level depth of sub-directory) to generate example reST files.

Iterate through each example directory and any of its sub-directories (creates sub-sections) that has a header/index file. Generate gallery example ReST files and index.rst file(s).

If nested_sections=True we generate index.rst files for all sub-directories, which includes toctree linking to all sub-dir examples. The root example directory index.rst file will contain, in sequence,:

root gallery header then thumbnails,
toctree linking all examples in root gallery,
sub-section header followed by sub-section thumbnails, for all subsections,
a second final toctree, at the end of the file, linking to all sub-section index files.

If nested_sections=True we generate a single index.rst file per example directory. It will contain headers for the root gallery and each sub-section, with each header followed by a toctree linking to every example in the root gallery/sub-section.

sphinx_gallery.gen_gallery.get_default_config_value(key)[source]#: Get default configuration function.

sphinx_gallery.gen_gallery.get_subsections(srcdir, examples_dir, gallery_conf, check_for_header=True)[source]#

Return the list of subsections of a gallery.

Parameters:

srcdir (str) – absolute path to directory containing conf.py
examples_dir (str) – path to the examples directory relative to conf.py
gallery_conf (Dict[str, Any]) – Sphinx-Gallery configuration dictionary.
check_for_header (bool) – only return subfolders that contain a GALLERY_HEADER file, default True

Returns:

out – sorted list of gallery subsection folder names

Return type:

list

sphinx_gallery.gen_gallery.setup(app)[source]#: Setup Sphinx-Gallery sphinx extension.

sphinx_gallery.gen_gallery.setup_module()[source]#: Hack to stop nosetests running setup() above.

sphinx_gallery.gen_gallery.setup_template_link_getters(app, pagename, templatename, context, doctree)[source]#

Set up the getters for download and launcher links.

The getters are added to the sphinx context so as to be used in templates.

sphinx_gallery.gen_gallery.summarize_failing_examples(app, exception)[source]#

Collects the list of falling examples and prints them with a traceback.

Raises ValueError if there where failing examples.

sphinx_gallery.gen_gallery.touch_empty_backreferences(app, what, name, obj, options, lines)[source]#

Generate empty back-reference example files.

This avoids inclusion errors/warnings if there are no gallery examples for a class / module that is being parsed by autodoc.

sphinx_gallery.gen_gallery.update_gallery_conf_builder_inited(app)[source]#: Update the the sphinx-gallery config at builder-inited.

sphinx_gallery.gen_gallery.write_api_entries(app, what, name, obj, options, lines)[source]#

Write api entries to _sg_api_entries configuration.

To connect to autodoc-process-docstring event.

Parameters:

app – The Sphinx application object.
what (str) – The type of the object which the docstring belongs to. One of “module”, “class”, “exception”, “function”, “method”, “attribute”.
name – The fully qualified name of the object.
obj – The object itself.
options – The options given to the directive: an object with attributes inherited_members, undoc_members, show_inheritance and no-index that are true if the flag option of same name was given to the auto directive.
lines – The lines of the docstring, see above.

sphinx_gallery.gen_gallery.write_api_entry_usage(app, docname, source)[source]#

Write an html page describing which API entries are used and unused.

To document and graph only those API entries that are used by autodoc, we have to wait for autodoc to finish and hook into the source-read event. This intercepts the text from the rst such that it can be modified. Since, we only touched an empty file, we have to add 1) a list of all the API entries that are unused and a graph of the number of unused API entries per module and 2) a list of API entries that are used in examples, each with a sub-list of which examples that API entry is used in, and a graph that connects all of the API entries in a module to the examples that they are used in.

Parameters:

app – The Sphinx application object.
docname – Docname of the document currently being parsed.
source – List whose single element is the contents of the source file

sphinx_gallery.gen_gallery.write_computation_times(gallery_conf, target_dir, costs)[source]#

Write computation times to sg_execution_times.rst.

Parameters:

gallery_conf (Dict[str, Any]) – Sphinx-Gallery configuration dictionary.
target_dir (str | None) – Path to directory where example python source file are.
costs (List[Dict]) – List of dicts of computation costs and paths, see gen_rst.py for details.

sphinx_gallery.gen_gallery.write_junit_xml(gallery_conf, target_dir, costs)[source]#

Write JUnit XML file of example run times, successes, and failures.

Parameters:

gallery_conf (Dict[str, Any]) – Sphinx-Gallery configuration dictionary.
target_dir (Union[str, pathlib.Path]) – Build directory.
costs (List[Tuple[Tuple[float], str]]) – List of dicts of computation costs and paths, see gen_rst.py for details.

Classes#

class sphinx_gallery.gen_gallery.DefaultResetArgv[source]#: Provides default ‘reset_argv’ callable that returns empty list.