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.check_duplicate_filenames(files)[source]#: Check for duplicate filenames across gallery directories.

sphinx_gallery.gen_gallery.check_spaces_in_filenames(files)[source]#: Check for spaces in filenames across example directories.

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

sphinx_gallery.gen_gallery.collect_gallery_files(examples_dirs, gallery_conf)[source]#: Collect python files from the gallery example directories.

sphinx_gallery.gen_gallery.cost_name_key(cost_name)[source]#

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

Start the Sphinx-Gallery configuration and recursively scan the examples directories in order to populate the examples gallery.

We create a 2-level nested structure by iterating through every sibling folder of the current index file. In each of these folders, we look for a section index file, for which we generate a toctree pointing to sibling scripts. Then, we append the content of this section index file to the current index file, after we remove toctree (to keep a clean nested structure) and sphinx tags (to prevent tag duplication) Eventually, we create a toctree in the current index file which points to section index files.

sphinx_gallery.gen_gallery.get_default_config_value(key)[source]#

sphinx_gallery.gen_gallery.get_subsections(srcdir, examples_dir, gallery_conf, check_for_index=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) – The gallery configuration.
check_for_index (bool) – only return subfolders with a ReadMe, default True

Returns:

out – sorted list of gallery subsection folder names

Return type:

list

sphinx_gallery.gen_gallery.init_api_usage(gallery_dir)[source]#

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

sphinx_gallery.gen_gallery.setup_module()[source]#

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

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.

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

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

Classes#

class sphinx_gallery.gen_gallery.DefaultResetArgv[source]#