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_api_usage_files(app, exception)[source]#
Remove api usage .dot files.
To connect to ‘build-finished’ event.
- sphinx_gallery.gen_gallery.collect_gallery_files(examples_dirs, gallery_conf)[source]#
Collect python files from the gallery example directories.
- 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]#
Get default configuration function.
- 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:
- Returns:
out – sorted list of gallery subsection folder names
- Return type:
- 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.
- 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.