Utilities
*********

Sphinx provides utility classes and functions to develop extensions.


Base classes for components
===========================

These base classes are useful to allow your extensions to obtain
Sphinx components (e.g. "Config", "BuildEnvironment" and so on)
easily.

Note:

  The subclasses of them might not work with bare docutils because
  they are strongly coupled with Sphinx.

class sphinx.transforms.SphinxTransform(document, startnode=None)

   A base class of Transforms.

   Compared with "docutils.transforms.Transform", this class improves
   accessibility to Sphinx APIs.

   property app: Sphinx

      Reference to the "Sphinx" object.

   property config: Config

      Reference to the "Config" object.

   property env: BuildEnvironment

      Reference to the "BuildEnvironment" object.

class sphinx.transforms.post_transforms.SphinxPostTransform(document, startnode=None)

   A base class of post-transforms.

   Post transforms are invoked to modify the document to restructure
   it for outputting. They resolve references, convert images, do
   special transformation for each output formats and so on.  This
   class helps to implement these post transforms.

   apply(**kwargs: Any) -> None

      Override to apply the transform to the document tree.

   is_supported() -> bool

      Check this transform working for current builder.

   run(**kwargs: Any) -> None

      Main method of post transforms.

      Subclasses should override this method instead of "apply()".

class sphinx.util.docutils.SphinxDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

   A base class for Sphinx directives.

   This class provides helper methods for Sphinx directives.

   Note:

     The subclasses of this class might not work with docutils. This
     class is strongly coupled with Sphinx.

   get_location() -> str

      Get current location info for logging.

   get_source_info() -> tuple[str, int]

      Get source and line number.

   set_source_info(node: Node) -> None

      Set source and line number to the node.

   property config: Config

      Reference to the "Config" object.

   property env: BuildEnvironment

      Reference to the "BuildEnvironment" object.

class sphinx.util.docutils.SphinxRole

   A base class for Sphinx roles.

   This class provides helper methods for Sphinx roles.

   Note:

     The subclasses of this class might not work with docutils. This
     class is strongly coupled with Sphinx.

   get_location() -> str

      Get current location info for logging.

   property config: Config

      Reference to the "Config" object.

   content: list[str]

      A list of strings, the directive content for customization

   property env: BuildEnvironment

      Reference to the "BuildEnvironment" object.

   inliner: Inliner

      The "docutils.parsers.rst.states.Inliner" object.

   lineno: int

      The line number where the interpreted text begins.

   name: str

      The role name actually used in the document.

   options: dict

      A dictionary of directive options for customization

   rawtext: str

      A string containing the entire interpreted text input.

   text: str

      The interpreted text content.

class sphinx.util.docutils.ReferenceRole

   A base class for reference roles.

   The reference roles can accept "link title <target>" style as a
   text for the role.  The parsed result; link title and target will
   be stored to "self.title" and "self.target".

   disabled: bool

      A boolean indicates the reference is disabled.

   has_explicit_title: bool

      A boolean indicates the role has explicit title or not.

   target: str

      The link target for the interpreted text.

   title: str

      The link title for the interpreted text.

class sphinx.transforms.post_transforms.images.ImageConverter(*args: Any, **kwargs: Any)

   A base class for image converters.

   An image converter is kind of Docutils transform module.  It is
   used to convert image files which are not supported by a builder to
   the appropriate format for that builder.

   For example, "LaTeX builder" supports PDF, PNG and JPEG as image
   formats.  However it does not support SVG images. For such case,
   using image converters allows to embed these unsupported images
   into the document.  One of the image converters;
   sphinx.ext.imgconverter can convert a SVG image to PNG format using
   Imagemagick internally.

   There are three steps to make your custom image converter:

   1. Make a subclass of "ImageConverter" class

   2. Override "conversion_rules", "is_available()" and "convert()"

   3. Register your image converter to Sphinx using
      "Sphinx.add_post_transform()"

   convert(_from: str, _to: str) -> bool

      Convert an image file to the expected format.

      *_from* is a path of the source image file, and *_to* is a path
      of the destination file.

   is_available() -> bool

      Return the image converter is available or not.

   available: bool | None = None

      The converter is available or not.  Will be filled at the first
      call of the build.  The result is shared in the same process.

      Todo: This should be refactored not to store the state without
      class variable.

   conversion_rules: list[tuple[str, str]] = []

      A conversion rules the image converter supports. It is
      represented as a list of pair of source image format (mimetype)
      and destination one:

         conversion_rules = [
             ('image/svg+xml', 'image/png'),
             ('image/gif', 'image/png'),
             ('application/pdf', 'image/png'),
         ]

   default_priority = 200

      Numerical priority of this transform, 0 through 999 (override).


Utility components
==================

class sphinx.events.EventManager(app: Sphinx)

   Event manager for Sphinx.

   add(name: str) -> None

      Register a custom Sphinx event.

   connect(name: str, callback: Callable, priority: int) -> int

      Connect a handler to specific event.

   disconnect(listener_id: int) -> None

      Disconnect a handler.

   emit(name: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) -> list

      Emit a Sphinx event.

   emit_firstresult(name: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) -> Any

      Emit a Sphinx event and returns first result.

      This returns the result of the first handler that doesn't return
      "None".
