# 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: Sphinx, exception: Exception | None) → None

  Remove api usage .dot files.

  To connect to ‘build-finished’ event.

sphinx_gallery.gen_gallery.fill_gallery_conf_defaults(app: Sphinx, config: Any, check_keys: bool = True) → None

  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

  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

  Get default configuration function.

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

  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: Sphinx) → dict[str, Any]

  Setup Sphinx-Gallery sphinx extension.

sphinx_gallery.gen_gallery.setup_module() → None

  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

  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

  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

  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

  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

  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: Sphinx, docname: str, source: list[str]) → None

  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: dict[str, Any], target_dir: str | None, costs: list[ExampleCost]) → None

  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, costs: list[ExampleCost]) → None

  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[ExampleCost]) – List of example run costs.

## Classes

class sphinx_gallery.gen_gallery.DefaultResetArgv

  Provides default ‘reset_argv’ callable that returns empty list.