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.fill_gallery_conf_defaults(app: Sphinx, config: Any, check_keys: bool = True) → None[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: Sphinx) → None[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=False 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: str) → Any[source]#: Get default configuration function.

sphinx_gallery.gen_gallery.get_subsections(srcdir: str | Path | PathLike[str], examples_dir: str | Path | PathLike[str], gallery_conf: dict[str, Any], check_for_header: bool = True) → list[str][source]#

Return the list of subsections of a gallery.

Parameters:

srcdir (str | pathlib.Path) – absolute path to directory containing conf.py
examples_dir (str | pathlib.Path) – 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.merge_api_entries(app: Sphinx, env: BuildEnvironment, docnames: list[str], other: BuildEnvironment) → None[source]#

Merge the API entries collected by a parallel read worker.

To connect to env-merge-info event.

sphinx_gallery.gen_gallery.purge_api_entries(app: Sphinx, env: BuildEnvironment, docname: str) → None[source]#

Drop the API entries of a document that is about to be re-read.

To connect to env-purge-doc event.

sphinx_gallery.gen_gallery.setup(app: Sphinx) → dict[str, Any][source]#: Setup Sphinx-Gallery sphinx extension.

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

sphinx_gallery.gen_gallery.setup_template_link_getters(app: Sphinx, pagename: str, templatename: str, context: dict[str, Any], doctree: Any) → None[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: Sphinx, exception: Exception | None) → None[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: Sphinx, what: str, name: str, obj: Any, options: Any, lines: list[str]) → None[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: Sphinx) → None[source]#: Update the the sphinx-gallery config at builder-inited.

sphinx_gallery.gen_gallery.write_api_entries(app: Sphinx, what: str, name: str, obj: Any, options: Any, lines: list[str]) → None[source]#

Collect an API entry into the build environment.

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: Sphinx, env: BuildEnvironment) → list[str][source]#

Write sg_api_usage.rst and re-read it if it changed.

To connect to the ‘env-updated’ event, which is the first point at which every autodoc-process-docstring has fired – including those in parallel read workers, whose entries have been merged back by then. Generating here rather than at ‘source-read’ means a build whose API usage is unchanged leaves the file untouched, so Sphinx skips the document entirely on the next build.

Returns:: docnames – The documents that need to be written.
Return type:: list of str

sphinx_gallery.gen_gallery.write_computation_times(gallery_conf: dict[str, Any], target_dir: str | Path | PathLike[str] | None, costs: list[ExampleCost]) → None[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[ExampleCost]) – List of example run costs.

sphinx_gallery.gen_gallery.write_junit_xml(gallery_conf: dict[str, Any], target_dir: str | Path | PathLike[str], costs: list[ExampleCost]) → None[source]#

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

Parameters:

gallery_conf (Dict[str, Any]) – Sphinx-Gallery configuration dictionary.
target_dir (str | pathlib.Path) – Build directory.
costs (List[ExampleCost]) – List of example run costs.

Classes#

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