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(name)

   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.

Sphinx.require_sphinx(version)

   Check the Sphinx version if requested.

   Compare *version* (which must be a "major.minor" version string,
   e.g. "'1.1'") with the version of the running Sphinx, and abort the
   build when it is too old.

   New in version 1.0.

Sphinx.connect(event, callback)

   Register *callback* to be called when *event* is emitted.

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

   The method returns a "listener ID" that can be used as an argument
   to "disconnect()".

Sphinx.disconnect(listener_id)

   Unregister callback by *listener_id*.

Sphinx.add_builder(builder)

   Register a new builder.

   *builder* must be a class that inherits from "Builder".

   Changed in version 1.8: Add *override* keyword.

Sphinx.add_config_value(name, default, rebuild)

   Register a configuration value.

   This is necessary for Sphinx to recognize new values and set
   default values accordingly.  The *name* should be prefixed with the
   extension name, to avoid clashes.  The *default* value can be any
   Python object. The string value *rebuild* 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.

   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.

   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.

Sphinx.add_event(name)

   Register an event called *name*.

   This is needed to be able to emit it.

Sphinx.set_translator(name, translator_class)

   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 custom
   translator and define custom nodes for the translator (see
   "add_node()").

   New in version 1.3.

   Changed in version 1.8: Add *override* keyword.

Sphinx.add_node(node, **kwds)

   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.

   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): pass

      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, figtype, title_getter=None, **kwds)

   Register a Docutils node class as a numfig target.

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

   *figtype* is a type of enumerable nodes.  Each figtypes have
   individual numbering sequences.  As a system figtypes, "figure",
   "table" and "code-block" are defined.  It is able to add custom
   nodes to these default figtypes.  It is also able to define new
   custom figtype if new figtype is given.

   *title_getter* is 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.

   Other keyword arguments are used for node visitor functions. See
   the "Sphinx.add_node()" for details.

   New in version 1.4.

Sphinx.add_directive(name, func, content, arguments, **options)

Sphinx.add_directive(name, directiveclass)

   Register a Docutils directive.

   *name* must be the prospective directive name.  There are two
   possible ways to write a directive:

   * In the docutils 0.4 style, *obj* is the directive function.
     *content*, *arguments* and *options* are set as attributes on the
     function and determine whether the directive has content,
     arguments and options, respectively.  **This style is
     deprecated.**

   * In the docutils 0.5 style, *obj* is the directive class. It must
     already have attributes named *has_content*,
     *required_arguments*, *optional_arguments*,
     *final_argument_whitespace* and *option_spec* that correspond to
     the options for the function way.  See the Docutils docs for
     details.

   The directive class must inherit from the class
   "docutils.parsers.rst.Directive".

   For example, the (already existing) "literalinclude" directive
   would be added like this:

      from docutils.parsers.rst import Directive, directives

      class LiteralIncludeDirective(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):
              ...

      add_directive('literalinclude', LiteralIncludeDirective)

   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, role)

   Register a Docutils role.

   *name* must be the role name that occurs in the source, *role* the
   role function. Refer to the Docutils documentation for more
   information.

   Changed in version 1.8: Add *override* keyword.

Sphinx.add_generic_role(name, nodeclass)

   Register a generic Docutils role.

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

   New in version 0.6.

   Changed in version 1.8: Add *override* keyword.

Sphinx.add_domain(domain)

   Register a domain.

   Make the given *domain* (which must be a class; more precisely, a
   subclass of "Domain") known to Sphinx.

   New in version 1.0.

   Changed in version 1.8: Add *override* keyword.

Sphinx.override_domain(domain)

   Override a registered domain.

   Make the given *domain* class known to Sphinx, assuming that there
   is already a domain with its ".name".  The new domain must be a
   subclass of the existing one.

   New in version 1.0.

   Deprecated since version 1.8: Integrated to "add_domain()".

Sphinx.add_directive_to_domain(domain, name, func, content, arguments, **options)

Sphinx.add_directive_to_domain(domain, name, directiveclass)

   Register a Docutils directive in a domain.

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

   New in version 1.0.

   Changed in version 1.8: Add *override* keyword.

Sphinx.add_role_to_domain(domain, name, role)

   Register a Docutils role in a domain.

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

   New in version 1.0.

   Changed in version 1.8: Add *override* keyword.

Sphinx.add_index_to_domain(domain, index)

   Register a custom index for a domain.

   Add a custom *index* class to the domain named *domain*.  *index*
   must be a subclass of "Index".

   New in version 1.0.

   Changed in version 1.8: Add *override* keyword.

Sphinx.add_object_type(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None, objname='', doc_field_types=[])

   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 Cross-referencing syntax).

   Changed in version 1.8: Add *override* keyword.

Sphinx.add_crossref_type(directivename, rolename, indextemplate='', ref_nodeclass=None, objname='')

   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.)

   Changed in version 1.8: Add *override* keyword.

Sphinx.add_transform(transform)

   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.


   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)

   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.

Sphinx.add_js_file(filename, **kwargs)

   Register a JavaScript file to include in the HTML output.

   Add *filename* to the list of JavaScript files that the default
   HTML template will include.  The filename must be relative to the
   HTML static path , or a full URI with scheme.  The keyword
   arguments are also accepted for attributes of "<script>" tag.

   Example:

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

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

   New in version 0.5.

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

Sphinx.add_css_file(filename, **kwargs)

   Register a stylesheet to include in the HTML output.

   Add *filename* to the list of CSS files that the default HTML
   template will include.  The filename must be relative to the HTML
   static path, or a full URI with scheme.  The keyword arguments are
   also accepted for attributes of "<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" />

   New in version 1.0.

   Changed in version 1.6: Optional "alternate" and/or "title"
   attributes can be supplied with the *alternate* (of boolean type)
   and *title* (a string) arguments. 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.

Sphinx.add_latex_package(packagename, options=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
   *usepackage* declaration.

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

   New in version 1.3.

Sphinx.add_lexer(alias, lexer)

   Register a new lexer for source code.

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

   New in version 0.6.

   Changed in version 2.1: Take a lexer class as an argument.  An
   instance of lexers are still supported until Sphinx-3.x.

Sphinx.add_autodocumenter(cls)

   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 to auto-document new
   types of objects.  See the source of the autodoc module for
   examples on how to subclass "Documenter".

   Todo: Add real docs for Documenter and subclassing

   New in version 0.6.

   Changed in version 2.2: Add *override* keyword.

Sphinx.add_autodoc_attrgetter(type, getter)

   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()".

   New in version 0.6.

Sphinx.add_search_language(cls)

   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".

   New in version 1.1.

Sphinx.add_source_suffix(suffix, filetype)

   Register a suffix of source files.

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

   New in version 1.8.

Sphinx.add_source_parser(parser)

   Register a parser class.

   New 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)

   Register an environment collector class.

   Refer to Environment Collector API.

   New in version 1.6.

Sphinx.add_html_theme(name, theme_path)

   Register a HTML Theme.

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

   New in version 1.6.

Sphinx.add_html_math_renderer(name, inline_renderers, block_renderers)

   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.

   New in version 1.8.

Sphinx.add_message_catalog(catalog, locale_dir)

   Register a message catalog.

   The *catalog* is a name of catalog, and *locale_dir* is a base path
   of message catalog.  For more details, see
   "sphinx.locale.get_translation()".

   New in version 1.8.

Sphinx.is_parallel_allowed(typ)

   Check parallel processing is allowed or not.

   "typ" is a type of processing; "'read'" or "'write'".

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, *arguments)

      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!

   emit_firstresult(event, *arguments)

      Emit *event* and pass *arguments* to the callback functions.

      Return the result of the first callback that doesn't return
      "None".

      New in version 0.5.


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 core events
==================

These events are known to the core.  The arguments shown are given to
the registered event handlers.  Use "Sphinx.connect()" in an
extension's "setup" function (note that "conf.py" can also have a
"setup" function) to connect handlers to the events.  Example:

   def source_read_handler(app, docname, source):
       print('do something here...')

   def setup(app):
       app.connect('source-read', source_read_handler)

builder-inited(app)

   Emitted when the builder object has been created.  It is available
   as "app.builder".

config-inited(app, config)

   Emitted when the config object has been initialized.

   New in version 1.8.

env-get-outdated(app, env, added, changed, removed)

   Emitted when the environment determines which source files have
   changed and should be re-read.  *added*, *changed* and *removed*
   are sets of docnames that the environment has determined.  You can
   return a list of docnames to re-read in addition to these.

   New in version 1.1.

env-purge-doc(app, env, docname)

   Emitted when all traces of a source file should be cleaned from the
   environment, that is, if the source file is removed or before it is
   freshly read.  This is for extensions that keep their own caches in
   attributes of the environment.

   For example, there is a cache of all modules on the environment.
   When a source file has been changed, the cache's entries for the
   file are cleared, since the module declarations could have been
   removed from the file.

   New in version 0.5.

env-before-read-docs(app, env, docnames)

   Emitted after the environment has determined the list of all added
   and changed files and just before it reads them.  It allows
   extension authors to reorder the list of docnames (*inplace*)
   before processing, or add more docnames that Sphinx did not
   consider changed (but never add any docnames that are not in
   "env.found_docs").

   You can also remove document names; do this with caution since it
   will make Sphinx treat changed files as unchanged.

   New in version 1.3.

source-read(app, docname, source)

   Emitted when a source file has been read.  The *source* argument is
   a list whose single element is the contents of the source file.
   You can process the contents and replace this item to implement
   source-level transformations.

   For example, if you want to use "$" signs to delimit inline math,
   like in LaTeX, you can use a regular expression to replace "$...$"
   by ":math:`...`".

   New in version 0.5.

doctree-read(app, doctree)

   Emitted when a doctree has been parsed and read by the environment,
   and is about to be pickled.  The *doctree* can be modified in-
   place.

missing-reference(app, env, node, contnode)

   Emitted when a cross-reference to a Python module or object cannot
   be resolved.  If the event handler can resolve the reference, it
   should return a new docutils node to be inserted in the document
   tree in place of the node *node*.  Usually this node is a
   "reference" node containing *contnode* as a child.

   Parameters:
      * **env** -- The build environment ("app.builder.env").

      * **node** -- The "pending_xref" node to be resolved.  Its
        attributes "reftype", "reftarget", "modname" and "classname"
        attributes determine the type and target of the reference.

      * **contnode** -- The node that carries the text and formatting
        inside the future reference and should be a child of the
        returned reference node.

   New in version 0.5.

doctree-resolved(app, doctree, docname)

   Emitted when a doctree has been "resolved" by the environment, that
   is, all references have been resolved and TOCs have been inserted.
   The *doctree* can be modified in place.

   Here is the place to replace custom nodes that don't have visitor
   methods in the writers, so that they don't cause errors when the
   writers encounter them.

env-merge-info(app, env, docnames, other)

   This event is only emitted when parallel reading of documents is
   enabled.  It is emitted once for every subprocess that has read
   some documents.

   You must handle this event in an extension that stores data in the
   environment in a custom location.  Otherwise the environment in the
   main process will not be aware of the information stored in the
   subprocess.

   *other* is the environment object from the subprocess, *env* is the
   environment from the main process.  *docnames* is a set of document
   names that have been read in the subprocess.

   For a sample of how to deal with this event, look at the standard
   "sphinx.ext.todo" extension.  The implementation is often similar
   to that of "env-purge-doc", only that information is not removed,
   but added to the main environment from the other environment.

   New in version 1.3.

env-updated(app, env)

   Emitted when the "update()" method of the build environment has
   completed, that is, the environment and all doctrees are now up-to-
   date.

   You can return an iterable of docnames from the handler.  These
   documents will then be considered updated, and will be (re-)written
   during the writing phase.

   New in version 0.5.

   Changed in version 1.3: The handlers' return value is now used.

env-check-consistency(app, env)

   Emitted when Consistency checks phase.  You can check consistency
   of metadata for whole of documents.

   New in version 1.6: As a **experimental** event

html-collect-pages(app)

   Emitted when the HTML builder is starting to write non-document
   pages.  You can add pages to write by returning an iterable from
   this event consisting of "(pagename, context, templatename)".

   New in version 1.0.

html-page-context(app, pagename, templatename, context, doctree)

   Emitted when the HTML builder has created a context dictionary to
   render a template with -- this can be used to add custom elements
   to the context.

   The *pagename* argument is the canonical name of the page being
   rendered, that is, without ".html" suffix and using slashes as path
   separators.  The *templatename* is the name of the template to
   render, this will be "'page.html'" for all pages from reST
   documents.

   The *context* argument is a dictionary of values that are given to
   the template engine to render the page and can be modified to
   include custom values.  Keys must be strings.

   The *doctree* argument will be a doctree when the page is created
   from a reST documents; it will be "None" when the page is created
   from an HTML template alone.

   You can return a string from the handler, it will then replace
   "'page.html'" as the HTML template for this page.

   New in version 0.4.

   Changed in version 1.3: The return value can now specify a template
   name.

build-finished(app, exception)

   Emitted when a build has finished, before Sphinx exits, usually
   used for cleanup.  This event is emitted even when the build
   process raised an exception, given as the *exception* argument.
   The exception is reraised in the application after the event
   handlers have run.  If the build process raised no exception,
   *exception* will be "None".  This allows to customize cleanup
   actions depending on the exception status.

   New in version 0.5.


Checking the Sphinx version
===========================

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

sphinx.version_info = (2, 3, 0, '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.

   New in version 1.2: Before version 1.2, check the string
   "sphinx.__version__".


The Config object
=================

class sphinx.config.Config(*args)

   Configuration file abstraction.

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

   It is exposed via the "sphinx.application.Application.config" and
   "sphinx.environment.Environment.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, theme=None, dirs=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()

      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, context)

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

   render_string(template, context)

      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, orig_exc=None)

   Extension error.

exception sphinx.errors.ThemeError

   Theme error.

exception sphinx.errors.VersionRequirementError

   Incompatible Sphinx version error.
