Sphinx

# Application API

Each Sphinx extension is a Python module with at least a `setup()` function. This function is called at initialization time with one argument, the application object representing the Sphinx process.

class sphinx.application.Sphinx

  This application object has the public API described in the following.

## Extension setup

These methods are usually called in an extension’s `setup()` function.

Examples of using the Sphinx extension API can be seen in the `sphinx.ext` package.

Sphinx.setup_extension(extname: str) → None

  Import and setup a Sphinx extension module.

  Load the extension given by the module name. Use this if your extension needs the features provided by another extension. No-op if called twice.

static Sphinx.require_sphinx(version: tuple[int, int] | str) → None

  Check the Sphinx version if requested.

  Compare version with the version of the running Sphinx, and abort the build when it is too old.

  Parameters:

    version – The required version in the form of `major.minor` or `(major, minor)`.

  Added in version 1.0.

  Changed in version 7.1: Type of version now allows `(major, minor)` form.

Sphinx.connect(event: Literal['config-inited'], callback: Callable[[Sphinx, Config], None], priority: int = 500) → int
Sphinx.connect(event: Literal['builder-inited'], callback: Callable[[Sphinx], None], priority: int = 500) → int
Sphinx.connect(event: Literal['env-get-outdated'], callback: Callable[[Sphinx, BuildEnvironment, Set[str], Set[str], Set[str]], Sequence[str]], priority: int = 500) → int
Sphinx.connect(event: Literal['env-before-read-docs'], callback: Callable[[Sphinx, BuildEnvironment, list[str]], None], priority: int = 500) → int
Sphinx.connect(event: Literal['env-purge-doc'], callback: Callable[[Sphinx, BuildEnvironment, str], None], priority: int = 500) → int
Sphinx.connect(event: Literal['source-read'], callback: Callable[[Sphinx, str, list[str]], None], priority: int = 500) → int
Sphinx.connect(event: Literal['include-read'], callback: Callable[[Sphinx, Path, str, list[str]], None], priority: int = 500) → int
Sphinx.connect(event: Literal['doctree-read'], callback: Callable[[Sphinx, nodes.document], None], priority: int = 500) → int
Sphinx.connect(event: Literal['env-merge-info'], callback: Callable[[Sphinx, BuildEnvironment, Set[str], BuildEnvironment], None], priority: int = 500) → int
Sphinx.connect(event: Literal['env-updated'], callback: Callable[[Sphinx, BuildEnvironment], str], priority: int = 500) → int
Sphinx.connect(event: Literal['env-get-updated'], callback: Callable[[Sphinx, BuildEnvironment], Iterable[str]], priority: int = 500) → int
Sphinx.connect(event: Literal['env-check-consistency'], callback: Callable[[Sphinx, BuildEnvironment], None], priority: int = 500) → int
Sphinx.connect(event: Literal['write-started'], callback: Callable[[Sphinx, Builder], None], priority: int = 500) → int
Sphinx.connect(event: Literal['doctree-resolved'], callback: Callable[[Sphinx, nodes.document, str], None], priority: int = 500) → int
Sphinx.connect(event: Literal['missing-reference'], callback: Callable[[Sphinx, BuildEnvironment, addnodes.pending_xref, nodes.TextElement], nodes.reference | None], priority: int = 500) → int
Sphinx.connect(event: Literal['warn-missing-reference'], callback: Callable[[Sphinx, Domain, addnodes.pending_xref], bool | None], priority: int = 500) → int
Sphinx.connect(event: Literal['build-finished'], callback: Callable[[Sphinx, Exception | None], None], priority: int = 500) → int
Sphinx.connect(event: Literal['html-collect-pages'], callback: Callable[[Sphinx], Iterable[tuple[str, dict[str, Any], str]]], priority: int = 500) → int
Sphinx.connect(event: Literal['html-page-context'], callback: Callable[[Sphinx, str, str, dict[str, Any], nodes.document], str | None], priority: int = 500) → int
Sphinx.connect(event: Literal['linkcheck-process-uri'], callback: Callable[[Sphinx, str], str | None], priority: int = 500) → int
Sphinx.connect(event: Literal['object-description-transform'], callback: Callable[[Sphinx, str, str, addnodes.desc_content], None], priority: int = 500) → int
Sphinx.connect(event: Literal['autodoc-process-docstring'], callback: _AutodocProcessDocstringListener, priority: int = 500) → int
Sphinx.connect(event: Literal['autodoc-before-process-signature'], callback: Callable[[Sphinx, Any, bool], None], priority: int = 500) → int
Sphinx.connect(event: Literal['autodoc-process-signature'], callback: Callable[[Sphinx, Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], str, Any, dict[str, bool], str | None, str | None], tuple[str | None, str | None] | None], priority: int = 500) → int
Sphinx.connect(event: Literal['autodoc-process-bases'], callback: Callable[[Sphinx, str, Any, dict[str, bool], list[str]], None], priority: int = 500) → int
Sphinx.connect(event: Literal['autodoc-skip-member'], callback: Callable[[Sphinx, Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], str, Any, bool, dict[str, bool]], bool], priority: int = 500) → int
Sphinx.connect(event: Literal['todo-defined'], callback: Callable[[Sphinx, todo_node], None], priority: int = 500) → int
Sphinx.connect(event: Literal['viewcode-find-source'], callback: Callable[[Sphinx, str], tuple[str, dict[str, tuple[Literal['class', 'def', 'other'], int, int]]]], priority: int = 500) → int
Sphinx.connect(event: Literal['viewcode-follow-imported'], callback: Callable[[Sphinx, str, str], str | None], priority: int = 500) → int
Sphinx.connect(event: str, callback: Callable[..., Any], priority: int = 500) → int

  Register callback to be called when event is emitted.

  For details on available core events and the arguments of callback functions, please see Event callbacks API.

  Parameters:

    - event – The name of target event

    - callback – Callback function for the event

    - priority – The priority of the callback. The callbacks will be invoked in order of priority (ascending).

  Returns:

    A listener ID. It can be used for `disconnect()`.

  Changed in version 3.0: Support priority

Sphinx.disconnect(listener_id: int) → None

  Unregister callback by listener_id.

  Parameters:

    listener_id – A listener_id that `connect()` returns

Sphinx.add_builder(builder: type[Builder], override: bool = False) → None

  Register a new builder.

  Parameters:

    - builder – A builder class

    - override – If true, install the builder forcedly even if another builder is already installed as the same name

  Changed in version 1.8: Add override keyword.

Sphinx.add_config_value(name: str, default: Any, rebuild: _ConfigRebuild, types: type | Collection[type] | ENUM = (), description: str = '') → None

  Register a configuration value.

  This is necessary for Sphinx to recognize new values and set default values accordingly.

  Parameters:

    - name – The name of the configuration value. It is recommended to be prefixed with the extension name (ex. `html_logo`, `epub_title`)

    - default – The default value of the configuration.

    - rebuild –

      The condition of rebuild. It must be one of those values:

      - `'env'` if a change in the setting only takes effect when a document is parsed – this means that the whole environment must be rebuilt.

      - `'html'` if a change in the setting needs a full rebuild of HTML documents.

      - `''` if a change in the setting will not need any special rebuild.

    - types – The type of configuration value. A list of types can be specified. For example, `[str]` is used to describe a configuration that takes string value.

    - description – A short description of the configuration value.

  Changed in version 0.4: If the default value is a callable, it will be called with the config object as its argument in order to get the default value. This can be used to implement config values whose default depends on other values.

  Changed in version 0.6: Changed rebuild from a simple boolean (equivalent to `''` or `'env'`) to a string. However, booleans are still accepted and converted internally.

  Added in version 7.4: The description parameter.

Sphinx.add_event(name: str) → None

  Register an event called name.

  This is needed to be able to emit it.

  Parameters:

    name – The name of the event

Sphinx.set_translator(name: str, translator_class: type[nodes.NodeVisitor], override: bool = False) → None

  Register or override a Docutils translator class.

  This is used to register a custom output translator or to replace a builtin translator. This allows extensions to use a custom translator and define custom nodes for the translator (see `add_node()`).

  Parameters:

    - name – The name of the builder for the translator

    - translator_class – A translator class

    - override – If true, install the translator forcedly even if another translator is already installed as the same name

  Added in version 1.3.

  Changed in version 1.8: Add override keyword.

Sphinx.add_node(node: type[Element], override: bool = False, **kwargs: _NodeHandlerPair) → None

  Register a Docutils node class.

  This is necessary for Docutils internals. It may also be used in the future to validate nodes in the parsed documents.

  Parameters:

    - node – A node class

    - kwargs – Visitor functions for each builder (see below)

    - override – If true, install the node forcedly even if another node is already installed as the same name

  Node visitor functions for the Sphinx HTML, LaTeX, text and manpage writers can be given as keyword arguments: the keyword should be one or more of `'html'`, `'latex'`, `'text'`, `'man'`, `'texinfo'` or any other supported translators, the value a 2-tuple of `(visit, depart)` methods. `depart` can be `None` if the `visit` function raises `docutils.nodes.SkipNode`. Example:

      class math(docutils.nodes.Element): ...

      def visit_math_html(self, node):
          self.body.append(self.starttag(node, 'math'))

      def depart_math_html(self, node):
          self.body.append('</math>')

      app.add_node(math, html=(visit_math_html, depart_math_html))

  Obviously, translators for which you don’t specify visitor methods will choke on the node when encountered in a document to translate.

  Changed in version 0.5: Added the support for keyword arguments giving visit functions.

Sphinx.add_enumerable_node(node: type[Element], figtype: str, title_getter: TitleGetter | None = None, override: bool = False, **kwargs: tuple[_NodeHandler, _NodeHandler]) → None

  Register a Docutils node class as a numfig target.

  Sphinx numbers the node automatically. And then the users can refer it using `numref`.

  Parameters:

    - node – A node class

    - figtype – The type of enumerable nodes. Each figtype has individual numbering sequences. As system figtypes, `figure`, `table` and `code-block` are defined. It is possible to add custom nodes to these default figtypes. It is also possible to define new custom figtype if a new figtype is given.

    - title_getter – A getter function to obtain the title of node. It takes an instance of the enumerable node, and it must return its title as string. The title is used to the default title of references for `ref`. By default, Sphinx searches `docutils.nodes.caption` or `docutils.nodes.title` from the node as a title.

    - kwargs – Visitor functions for each builder (same as `add_node()`)

    - override – If true, install the node forcedly even if another node is already installed as the same name

  Added in version 1.4.

Sphinx.add_directive(name: str, cls: type[Directive], override: bool = False) → None

  Register a Docutils directive.

  Parameters:

    - name – The name of the directive

    - cls – A directive class

    - override – If false, do not install it if another directive is already installed as the same name If true, unconditionally install the directive.

  For example, a custom directive named `my-directive` would be added like this:

      from docutils.parsers.rst import Directive, directives

      class MyDirective(Directive):
          has_content = True
          required_arguments = 1
          optional_arguments = 0
          final_argument_whitespace = True
          option_spec = {
              'class': directives.class_option,
              'name': directives.unchanged,
          }

          def run(self):
              pass

      def setup(app):
          app.add_directive('my-directive', MyDirective)

  For more details, see the Docutils docs .

  Changed in version 0.6: Docutils 0.5-style directive classes are now supported.

  Deprecated since version 1.8: Docutils 0.4-style (function based) directives support is deprecated.

  Changed in version 1.8: Add override keyword.

Sphinx.add_role(name: str, role: Any, override: bool = False) → None

  Register a Docutils role.

  Parameters:

    - name – The name of role

    - role – A role function

    - override – If false, do not install it if another role is already installed as the same name If true, unconditionally install the role.

  For more details about role functions, see the Docutils docs .

  Changed in version 1.8: Add override keyword.

Sphinx.add_generic_role(name: str, nodeclass: type[Node], override: bool = False) → None

  Register a generic Docutils role.

  Register a Docutils role that does nothing but wrap its contents in the node given by nodeclass.

  Parameters:

    override – If false, do not install it if another role is already installed as the same name If true, unconditionally install the role.

  Added in version 0.6.

  Changed in version 1.8: Add override keyword.

Sphinx.add_domain(domain: type[Domain], override: bool = False) → None

  Register a domain.

  Parameters:

    - domain – A domain class

    - override – If false, do not install it if another domain is already installed as the same name If true, unconditionally install the domain.

  Added in version 1.0.

  Changed in version 1.8: Add override keyword.

Sphinx.add_directive_to_domain(domain: str, name: str, cls: type[Directive], override: bool = False) → None

  Register a Docutils directive in a domain.

  Like `add_directive()`, but the directive is added to the domain named domain.

  Parameters:

    - domain – The name of target domain

    - name – A name of directive

    - cls – A directive class

    - override – If false, do not install it if another directive is already installed as the same name If true, unconditionally install the directive.

  Added in version 1.0.

  Changed in version 1.8: Add override keyword.

Sphinx.add_role_to_domain(domain: str, name: str, role: RoleFunction | XRefRole, override: bool = False) → None

  Register a Docutils role in a domain.

  Like `add_role()`, but the role is added to the domain named domain.

  Parameters:

    - domain – The name of the target domain

    - name – The name of the role

    - role – The role function

    - override – If false, do not install it if another role is already installed as the same name If true, unconditionally install the role.

  Added in version 1.0.

  Changed in version 1.8: Add override keyword.

Sphinx.add_index_to_domain(domain: str, index: type[Index], _override: bool = False) → None

  Register a custom index for a domain.

  Add a custom index class to the domain named domain.

  Parameters:

    - domain – The name of the target domain

    - index – The index class

    - override – If false, do not install it if another index is already installed as the same name If true, unconditionally install the index.

  Added in version 1.0.

  Changed in version 1.8: Add override keyword.

Sphinx.add_object_type(directivename: str, rolename: str, indextemplate: str = '', parse_node: Callable[[BuildEnvironment, str, addnodes.desc_signature], str] | None = None, ref_nodeclass: type[nodes.TextElement] | None = None, objname: str = '', doc_field_types: Sequence[Field] = (), override: bool = False) → None

  Register a new object type.

  This method is a very convenient way to add a new object type that can be cross-referenced. It will do this:

  - Create a new directive (called directivename) for documenting an object. It will automatically add index entries if indextemplate is nonempty; if given, it must contain exactly one instance of `%s`. See the example below for how the template will be interpreted.

  - Create a new role (called rolename) to cross-reference to these object descriptions.

  - If you provide parse_node, it must be a function that takes a string and a docutils node, and it must populate the node with children parsed from the string. It must then return the name of the item to be used in cross-referencing and index entries. See the `conf.py` file in the source for this documentation for an example.

  - The objname (if not given, will default to directivename) names the type of object. It is used when listing objects, e.g. in search results.

  For example, if you have this call in a custom Sphinx extension:

      app.add_object_type('directive', 'dir', 'pair: %s; directive')

  you can use this markup in your documents:

      .. rst:directive:: function

         Document a function.

      <...>

      See also the :rst:dir:`function` directive.

  For the directive, an index entry will be generated as if you had prepended

      .. index:: pair: function; directive

  The reference node will be of class `literal` (so it will be rendered in a proportional font, as appropriate for code) unless you give the ref_nodeclass argument, which must be a docutils node class. Most useful are `docutils.nodes.emphasis` or `docutils.nodes.strong` – you can also use `docutils.nodes.generated` if you want no further text decoration. If the text should be treated as literal (e.g. no smart quote replacement), but not have typewriter styling, use `sphinx.addnodes.literal_emphasis` or `sphinx.addnodes.literal_strong`.

  For the role content, you have the same syntactical possibilities as for standard Sphinx roles (see Syntax).

  If override is True, the given object_type is forcedly installed even if an object_type having the same name is already installed.

  Changed in version 1.8: Add override keyword.

Sphinx.add_crossref_type(directivename: str, rolename: str, indextemplate: str = '', ref_nodeclass: type[nodes.TextElement] | None = None, objname: str = '', override: bool = False) → None

  Register a new crossref object type.

  This method is very similar to `add_object_type()` except that the directive it generates must be empty, and will produce no output.

  That means that you can add semantic targets to your sources, and refer to them using custom roles instead of generic ones (like `ref`). Example call:

      app.add_crossref_type(
          'topic', 'topic', 'single: %s', docutils.nodes.emphasis
      )

  Example usage:

      .. topic:: application API

      The application API
      -------------------

      Some random text here.

      See also :topic:`this section <application API>`.

  (Of course, the element following the `topic` directive needn’t be a section.)

  Parameters:

    override – If false, do not install it if another cross-reference type is already installed as the same name If true, unconditionally install the cross-reference type.

  Changed in version 1.8: Add override keyword.

Sphinx.add_transform(transform: type[Transform]) → None

  Register a Docutils transform to be applied after parsing.

  Add the standard docutils `Transform` subclass transform to the list of transforms that are applied after Sphinx parses a reST document.

  Parameters:

    transform – A transform class

  priority range categories for Sphinx transforms
  Priority | Main purpose in Sphinx
  0-99 | Fix invalid nodes by docutils. Translate a doctree.
  100-299 | Preparation
  300-399 | early
  400-699 | main
  700-799 | Post processing. Deadline to modify text and referencing.
  800-899 | Collect referencing and referenced nodes. Domain processing.
  900-999 | Finalize and clean up.

  refs: Transform Priority Range Categories

Sphinx.add_post_transform(transform: type[Transform]) → None

  Register a Docutils transform to be applied before writing.

  Add the standard docutils `Transform` subclass transform to the list of transforms that are applied before Sphinx writes a document.

  Parameters:

    transform – A transform class

Sphinx.add_js_file(filename: str | None, priority: int = 500, loading_method: str | None = None, **kwargs: Any) → None

  Register a JavaScript file to include in the HTML output.

  Parameters:

    - filename – The name of a JavaScript file that the default HTML template will include. It must be relative to the HTML static path, or a full URI with scheme, or `None` . The `None` value is used to create an inline `<script>` tag. See the description of kwargs below.

    - priority – Files are included in ascending order of priority. If multiple JavaScript files have the same priority, those files will be included in order of registration. See list of “priority range for JavaScript files” below.

    - loading_method – The loading method for the JavaScript file. Either `'async'` or `'defer'` are allowed.

    - kwargs – Extra keyword arguments are included as attributes of the `<script>` tag. If the special keyword argument `body` is given, its value will be added as the content of the `<script>` tag.

  Example:

      app.add_js_file('example.js')
      # => <script src="_static/example.js"></script>

      app.add_js_file('example.js', loading_method='async')
      # => <script src="_static/example.js" async="async"></script>

      app.add_js_file(None, body="var myVariable = 'foo';")
      # => <script>var myVariable = 'foo';</script>

  priority range for JavaScript files
  Priority | Main purpose in Sphinx
  200 | default priority for built-in JavaScript files
  500 | default priority for extensions
  800 | default priority for `html_js_files`

  A JavaScript file can be added to the specific HTML page when an extension calls this method on `html-page-context` event.

  Added in version 0.5.

  Changed in version 1.8: Renamed from `app.add_javascript()`. And it allows keyword arguments as attributes of script tag.

  Changed in version 3.5: Take priority argument. Allow to add a JavaScript file to the specific page.

  Changed in version 4.4: Take loading_method argument. Allow to change the loading method of the JavaScript file.

Sphinx.add_css_file(filename: str, priority: int = 500, **kwargs: Any) → None

  Register a stylesheet to include in the HTML output.

  Parameters:

    - filename – The name of a CSS file that the default HTML template will include. It must be relative to the HTML static path, or a full URI with scheme.

    - priority – Files are included in ascending order of priority. If multiple CSS files have the same priority, those files will be included in order of registration. See list of “priority range for CSS files” below.

    - kwargs – Extra keyword arguments are included as attributes of the `<link>` tag.

  Example:

      app.add_css_file('custom.css')
      # => <link rel="stylesheet" href="_static/custom.css" type="text/css" />

      app.add_css_file('print.css', media='print')
      # => <link rel="stylesheet" href="_static/print.css"
      #          type="text/css" media="print" />

      app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
      # => <link rel="alternate stylesheet" href="_static/fancy.css"
      #          type="text/css" title="fancy" />

  priority range for CSS files
  Priority | Main purpose in Sphinx
  200 | default priority for built-in CSS files
  500 | default priority for extensions
  800 | default priority for `html_css_files`

  A CSS file can be added to the specific HTML page when an extension calls this method on `html-page-context` event.

  Added in version 1.0.

  Changed in version 1.6: Optional `alternate` and/or `title` attributes can be supplied with the arguments alternate (a Boolean) and title (a string). The default is no title and alternate = `False`. For more information, refer to the documentation.

  Changed in version 1.8: Renamed from `app.add_stylesheet()`. And it allows keyword arguments as attributes of link tag.

  Changed in version 3.5: Take priority argument. Allow to add a CSS file to the specific page.

Sphinx.add_latex_package(packagename: str, options: str | None = None, after_hyperref: bool = False) → None

  Register a package to include in the LaTeX source code.

  Add packagename to the list of packages that LaTeX source code will include. If you provide options, it will be taken to the usepackage declaration. If you set after_hyperref truthy, the package will be loaded after `hyperref` package.

      app.add_latex_package('mypackage')
      # => \usepackage{mypackage}
      app.add_latex_package('mypackage', 'foo,bar')
      # => \usepackage[foo,bar]{mypackage}

  Added in version 1.3.

  Added in version 3.1: after_hyperref option.

Sphinx.add_lexer(alias: str, lexer: type[Lexer]) → None

  Register a new lexer for source code.

  Use lexer to highlight code blocks with the given language alias.

  Added in version 0.6.

  Changed in version 2.1: Take a lexer class as an argument.

  Changed in version 4.0: Removed support for lexer instances as an argument.

Sphinx.add_autodocumenter(cls: type[Documenter], override: bool = False) → None

  Register a new documenter class for the autodoc extension.

  Add cls as a new documenter class for the `sphinx.ext.autodoc` extension. It must be a subclass of `sphinx.ext.autodoc.Documenter`. This allows auto-documenting new types of objects. See the source of the autodoc module for examples on how to subclass `Documenter`.

  If override is True, the given cls is forcedly installed even if a documenter having the same name is already installed.

  See Developing autodoc extensions.

  Added in version 0.6.

  Changed in version 2.2: Add override keyword.

Sphinx.add_autodoc_attrgetter(typ: type, getter: Callable[[Any, str, Any], Any]) → None

  Register a new `getattr`-like function for the autodoc extension.

  Add getter, which must be a function with an interface compatible to the `getattr()` builtin, as the autodoc attribute getter for objects that are instances of typ. All cases where autodoc needs to get an attribute of a type are then handled by this function instead of `getattr()`.

  Added in version 0.6.

Sphinx.add_search_language(cls: type[SearchLanguage]) → None

  Register a new language for the HTML search index.

  Add cls, which must be a subclass of `sphinx.search.SearchLanguage`, as a support language for building the HTML full-text search index. The class must have a lang attribute that indicates the language it should be used for. See `html_search_language`.

  Added in version 1.1.

Sphinx.add_source_suffix(suffix: str, filetype: str, override: bool = False) → None

  Register a suffix of source files.

  Same as `source_suffix`. The users can override this using the config setting.

  Parameters:

    override – If false, do not install it the same suffix is already installed. If true, unconditionally install the suffix.

  Added in version 1.8.

Sphinx.add_source_parser(parser: type[Parser], override: bool = False) → None

  Register a parser class.

  Parameters:

    override – If false, do not install it if another parser is already installed for the same suffix. If true, unconditionally install the parser.

  Added in version 1.4.

  Changed in version 1.8: suffix argument is deprecated. It only accepts parser argument. Use `add_source_suffix()` API to register suffix instead.

  Changed in version 1.8: Add override keyword.

Sphinx.add_env_collector(collector: type[EnvironmentCollector]) → None

  Register an environment collector class.

  Refer to Environment Collector API.

  Added in version 1.6.

Sphinx.add_html_theme(name: str, theme_path: str | os.PathLike[str]) → None

  Register a HTML Theme.

  The name is a name of theme, and theme_path is a full path to the theme (refs: Distribute your theme as a Python package).

  Added in version 1.6.

Sphinx.add_html_math_renderer(name: str, inline_renderers: _MathsInlineRenderers | None = None, block_renderers: _MathsBlockRenderers | None = None) → None

  Register a math renderer for HTML.

  The name is a name of math renderer. Both inline_renderers and block_renderers are used as visitor functions for the HTML writer: the former for inline math node (`nodes.math`), the latter for block math node (`nodes.math_block`). Regarding visitor functions, see `add_node()` for details.

  Added in version 1.8.

Sphinx.add_message_catalog(catalog: str, locale_dir: str | os.PathLike[str]) → None

  Register a message catalog.

  Parameters:

    - catalog – The name of the catalog

    - locale_dir – The base path of the message catalog

  For more details, see `sphinx.locale.get_translation()`.

  Added in version 1.8.

Sphinx.is_parallel_allowed(typ: str) → bool

  Check whether parallel processing is allowed or not.

  Parameters:

    typ – A type of processing; `'read'` or `'write'`.

Sphinx.set_html_assets_policy(policy: Literal['always', 'per_page']) → None

  Set the policy to include assets in HTML pages.

  - always: include the assets in all the pages

  - per_page: include the assets only in pages where they are used

exception sphinx.application.ExtensionError

  All these methods raise this exception if something went wrong with the extension API.

## Emitting events

class sphinx.application.Sphinx
  emit(event: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) → list[Any]

    Emit event and pass arguments to the callback functions.

    Return the return values of all callbacks as a list. Do not emit core Sphinx events in extensions!

    Parameters:

      - event – The name of event that will be emitted

      - args – The arguments for the event

      - allowed_exceptions – The list of exceptions that are allowed in the callbacks

    Changed in version 3.1: Added allowed_exceptions to specify path-through exceptions

  emit_firstresult(event: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) → Any

    Emit event and pass arguments to the callback functions.

    Return the result of the first callback that doesn’t return `None`.

    Parameters:

      - event – The name of event that will be emitted

      - args – The arguments for the event

      - allowed_exceptions – The list of exceptions that are allowed in the callbacks

    Added in version 0.5.

    Changed in version 3.1: Added allowed_exceptions to specify path-through exceptions

## Sphinx runtime information

The application object also provides runtime information as attributes.

Sphinx.project

  Target project. See `Project`.

Sphinx.srcdir

  Source directory.

Sphinx.confdir

  Directory containing `conf.py`.

Sphinx.doctreedir

  Directory for storing pickled doctrees.

Sphinx.outdir

  Directory for storing built document.

Sphinx.fresh_env_used

  True/False as to whether a new environment was created for this build, or None if the environment has not been initialised yet.

## Sphinx core events

Note

Moved to Event callbacks API.

## Checking the Sphinx version

Use this to adapt your extension to API changes in Sphinx.

sphinx.version_info: Final = (8, 2, 3, 'final', 0)

  Version info for better programmatic use.

  A tuple of five elements; for Sphinx version 1.2.1 beta 3 this would be `(1, 2, 1, 'beta', 3)`. The fourth element can be one of: `alpha`, `beta`, `rc`, `final`. `final` always has 0 as the last element.

  Added in version 1.2: Before version 1.2, check the string `sphinx.__version__`.

## The Config object

class sphinx.config.Config(config: dict[str, Any] | None = None, overrides: dict[str, Any] | None = None)

  Configuration file abstraction.

  The Config object makes the values of all config options available as attributes.

  It is exposed via the `Sphinx``.config` and `sphinx.environment.BuildEnvironment``.config` attributes. For example, to get the value of `language`, use either `app.config.language` or `env.config.language`.

## The template bridge

class sphinx.application.TemplateBridge

  This class defines the interface for a “template bridge”, that is, a class that renders templates given a template name and a context.

  init(builder: Builder, theme: Theme | None = None, dirs: list[str] | None = None) → None

    Called by the builder to initialize the template system.

    builder is the builder object; you’ll probably want to look at the value of `builder.config.templates_path`.

    theme is a `sphinx.theming.Theme` object or None; in the latter case, dirs can be list of fixed directories to look for templates.

  newest_template_mtime() → float

    Called by the builder to determine if output files are outdated because of template changes. Return the mtime of the newest template file that was changed. The default implementation returns `0`.

  render(template: str, context: dict[str, Any]) → None

    Called by the builder to render a template given as a filename with a specified context (a Python dictionary).

  render_string(template: str, context: dict[str, Any]) → str

    Called by the builder to render a template given as a string with a specified context (a Python dictionary).

## Exceptions

exception sphinx.errors.SphinxError

  Base class for Sphinx errors.

  This is the base class for “nice” exceptions. When such an exception is raised, Sphinx will abort the build and present the exception category and message to the user.

  Extensions are encouraged to derive from this exception for their custom errors.

  Exceptions not derived from `SphinxError` are treated as unexpected and shown to the user with a part of the traceback (and the full traceback saved in a temporary file).

  category

    Description of the exception “category”, used in converting the exception to a string (“category: message”). Should be set accordingly in subclasses.

exception sphinx.errors.ConfigError

  Configuration error.

exception sphinx.errors.ExtensionError(message: str, orig_exc: Exception | None = None, modname: str | None = None)

  Extension error.

exception sphinx.errors.ThemeError

  Theme error.

exception sphinx.errors.VersionRequirementError

  Incompatible Sphinx version error.