Extension API — flask-peewee v0.1.0 documentation

### Navigation

- index
- modules |
- flask-peewee v0.1.0 documentation »

# Extension 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. This application object has the following public API:

`Sphinx.` `setup_extension`(name)

  Load the extension given by the module name. Use this if your extension needs the features provided by another extension.

`Sphinx.` `add_builder`(builder)

  Register a new builder. builder must be a class that inherits from `Builder`.

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

`Sphinx.` `add_domain`(domain)

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

  New in version 1.0.

`Sphinx.` `override_domain`(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.

`Sphinx.` `add_index_to_domain`(domain, index)

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

  New in version 1.0.

`Sphinx.` `add_event`(name)

  Register an event called name. This is needed to be able to emit it.

`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 must be one or more of `'html'`, `'latex'`, `'text'`, `'man'`, 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_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, directiveclass 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 normally must inherit from the class `docutils.parsers.rst.Directive`. When writing a directive for usage in a Sphinx extension, you inherit from `sphinx.util.compat.Directive` instead which does the right thing even on docutils 0.4 (which doesn’t support directive classes otherwise).

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

      from docutils.parsers.rst import directives
      add_directive('literalinclude', literalinclude_directive,
                    content = 0, arguments = (1, 0, 0),
                    linenos = directives.flag,
                    language = direcitves.unchanged,
                    encoding = directives.encoding)

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

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

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

  New in version 1.0.

`Sphinx.` `add_role`(name, role)

  Register a Docutils role. name must be the role name that occurs in the source, role the role function (see the Docutils documentation on details).

`Sphinx.` `add_role_to_domain`(domain, name, role)

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

  New in version 1.0.

`Sphinx.` `add_generic_role`(name, nodeclass)

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

  New in version 0.6.

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

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

  For the role content, you have the same syntactical possibilities as for standard Sphinx roles (see Cross-referencing syntax).

  This method is also available under the deprecated alias `add_description_unit`.

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

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

      <...>

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

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

`Sphinx.` `add_transform`(transform)

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

`Sphinx.` `add_javascript`(filename)

  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, see :confval:`the docs for the config value <html_static_path>`. A full URI with scheme, like `http://example.org/foo.js`, is also supported.

  New in version 0.5.

`Sphinx.` `add_stylesheet`(filename)

  Add filename to the list of CSS files that the default HTML template will include. Like for `add_javascript()`, the filename must be relative to the HTML static path.

  New in version 1.0.

`Sphinx.` `add_lexer`(alias, lexer)

  Use lexer, which must be an instance of a Pygments lexer class, to highlight code blocks with the given language alias.

  New in version 0.6.

`Sphinx.` `add_autodocumenter`(cls)

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

  New in version 0.6.

`Sphinx.` `add_autodoc_attrgetter`(type, getter)

  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 type. 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.` `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 listener_id.

`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!

`Sphinx.` `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.` `require_sphinx`(version)

  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.

exception `sphinx.application.` `ExtensionError`

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

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

## Sphinx core events

These events are known to the core. The arguments shown are given to the registered event handlers.

## The template bridge

## Domain API

### Navigation

- index
- modules |
- flask-peewee v0.1.0 documentation »