# sphinx_gallery.directives

Custom Sphinx directives.

## Functions

sphinx_gallery.directives.depart_imgsg_html(self, node: imgsgnode) → None

  HTML depart node visitor function.

sphinx_gallery.directives.depart_imgsg_latex(self, node: imgsgnode) → None

  LaTeX depart node visitor function.

sphinx_gallery.directives.imagesg_addnode(app: sphinx.application.Sphinx) → None

  Add imgsgnode to Sphinx app with visitor functions for HTML and LaTeX.

sphinx_gallery.directives.visit_imgsg_html(self, node: imgsgnode) → None

  Handle HTML image tag depending on ‘srcset’ configuration.

  If ‘srcset’ is not None, copy images, generate image html tag with ‘srcset’ and add to HTML body. If ‘srcset’ is None run visit_image on node.

sphinx_gallery.directives.visit_imgsg_latex(self, node: imgsgnode) → None

  Copy images, set node[uri] to highest resolution image and call visit_image.

## Classes

class sphinx_gallery.directives.ImageSg(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

  Implements a directive to allow an optional hidpi image.

  Meant to be used with the image_srcset configuration option.

  e.g.:

      .. image-sg:: /plot_types/basic/images/sphx_glr_bar_001.png
          :alt: bar
          :srcset: /plot_types/basic/images/sphx_glr_bar_001.png,
                   /plot_types/basic/images/sphx_glr_bar_001_2_00x.png 2.00x
          :class: sphx-glr-single-img

  The resulting html is:

      <img src="sphx_glr_bar_001_hidpi.png"
          srcset="_images/sphx_glr_bar_001.png,
                  _images/sphx_glr_bar_001_2_00x.png 2x",
          alt="bar"
          class="sphx-glr-single-img" />

  final_argument_whitespace = False

    May the final argument contain whitespace?

  has_content = False

    May the directive have content?

  option_spec = {'alt': <function unchanged>, 'class': <function class_option>, 'srcset': <function unchanged>}

    Mapping of option names to validator functions.

  optional_arguments = 3

    Number of optional arguments after the required arguments.

  required_arguments = 1

    Number of required directive arguments.

  run() → List[Node]

    Update node contents.

class sphinx_gallery.directives.MiniGallery(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

  Custom directive to insert a mini-gallery.

  The required argument is one or more of the following:

  - fully qualified names of objects

  - pathlike strings to example Python files

  - glob-style pathlike strings to example Python files

  The string list of arguments is separated by spaces.

  The mini-gallery will be the subset of gallery examples that make use of that object from that specific namespace

  Options:

  - add-heading adds a heading to the mini-gallery. If an argument is provided, it uses that text for the heading. Otherwise, it uses default text.

  - heading-level specifies the heading level of the heading as a single character. If omitted, the default heading level is ‘^’.

  final_argument_whitespace = True

    May the final argument contain whitespace?

  has_content = True

    May the directive have content?

  option_spec = {'add-heading': <function unchanged>, 'heading-level': <function single_char_or_unicode>}

    Mapping of option names to validator functions.

  optional_arguments = 1

    Number of optional arguments after the required arguments.

  required_arguments = 0

    Number of required directive arguments.

  run() → list[Any]

    Generate mini-gallery from backreference and example files.

class sphinx_gallery.directives.imgsgnode(rawsource: str = '', *children, **attributes: Any)

  Sphinx Gallery image node class.