diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index e91f623dd..607155544 100644 --- a/doc/extdev/appapi.rst +++ b/doc/extdev/appapi.rst @@ -25,20 +25,26 @@ package. .. method:: 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. + needs the features provided by another extension. No-op if called twice. .. method:: Sphinx.add_builder(builder) - Register a new builder. *builder* must be a class that inherits from + Register a new builder. + + *builder* must be a class that inherits from :class:`~sphinx.builders.Builder`. .. method:: 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: + 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. @@ -46,33 +52,39 @@ package. documents. * ``''`` if a change in the setting will not need any special rebuild. - .. versionchanged:: 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. - .. versionchanged:: 0.6 Changed *rebuild* from a simple boolean (equivalent to ``''`` or ``'env'``) to a string. However, booleans are still accepted and converted internally. + .. versionchanged:: 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. + .. method:: Sphinx.add_domain(domain) - Make the given *domain* (which must be a class; more precisely, a subclass of - :class:`~sphinx.domains.Domain`) known to Sphinx. + Register a domain. + + Make the given *domain* (which must be a class; more precisely, a subclass + of :class:`~sphinx.domains.Domain`) known to Sphinx. .. versionadded:: 1.0 .. method:: 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. + 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. .. versionadded:: 1.0 .. method:: 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 :class:`~sphinx.domains.Index`. @@ -84,17 +96,20 @@ package. .. method:: 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 :meth:`add_node`). + 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 :meth:`add_node`). .. versionadded:: 1.3 -.. method:: Sphinx.add_node(node, **kwds) +.. method:: 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. + 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 @@ -114,22 +129,24 @@ package. 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. + Obviously, translators for which you don't specify visitor methods will + choke on the node when encountered in a document to translate. .. versionchanged:: 0.5 Added the support for keyword arguments giving visit functions. -.. method:: Sphinx.add_enumerable_node(node, figtype, title_getter=None, **kwds) +.. method:: 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 :rst:role:`numref`. + Register a Docutils node class as a numfig target. + + Sphinx numbers the node automatically. And then the users can refer it using + :rst:role:`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. + ``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. @@ -142,29 +159,31 @@ package. .. versionadded:: 1.4 -.. method:: Sphinx.add_directive(name, func, content, arguments, **options) +.. method:: 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: + Register a Docutils directive. - * In the docutils 0.4 style, *obj* is the directive function. *content*, + *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 + - 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 must inherit from the class - ``docutils.parsers.rst.Directive``. + The directive class must inherit from the class + ``docutils.parsers.rst.Directive``. - For example, the (already existing) :rst:dir:`literalinclude` directive would - be added like this: + For example, the (already existing) :rst:dir:`literalinclude` directive + would be added like this: .. code-block:: python @@ -178,9 +197,11 @@ package. .. versionchanged:: 0.6 Docutils 0.5-style directive classes are now supported. -.. method:: Sphinx.add_directive_to_domain(domain, name, func, content, arguments, **options) +.. method:: 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 :meth:`add_directive`, but the directive is added to the domain named *domain*. @@ -188,41 +209,52 @@ package. .. method:: 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). + 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. .. method:: Sphinx.add_role_to_domain(domain, name, role) + Register a Docutils role in a domain. + Like :meth:`add_role`, but the role is added to the domain named *domain*. .. versionadded:: 1.0 .. method:: Sphinx.add_generic_role(name, nodeclass) - Register a Docutils role that does nothing but wrap its contents in the - node given by *nodeclass*. + Register a generic Docutils role. + + Register a Docutils role that does nothing but wrap its contents in the node + given by *nodeclass*. + + Don't use ``roles.register_generic_role`` because it uses + ``register_canonical_role``. .. versionadded:: 0.6 .. method:: 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 :term:`object` type that can be cross-referenced. It will do this: - * Create a new directive (called *directivename*) for documenting an object. + - 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 + 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 :file:`conf.py` file in the source for this documentation for an example. - * The *objname* (if not given, will default to *directivename*) names the + - 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:: @@ -239,7 +271,8 @@ package. See also the :rst:dir:`function` directive. - For the directive, an index entry will be generated as if you had prepended :: + For the directive, an index entry will be generated as if you had + prepended:: .. index:: pair: function; directive @@ -256,10 +289,12 @@ package. standard Sphinx roles (see :ref:`xref-syntax`). This method is also available under the deprecated alias - ``add_description_unit``. + :meth:`add_description_unit`. .. method:: Sphinx.add_crossref_type(directivename, rolename, indextemplate='', ref_nodeclass=None, objname='') + Register a new crossref object type. + This method is very similar to :meth:`add_object_type` except that the directive it generates must be empty, and will produce no output. @@ -267,7 +302,8 @@ package. them using custom roles instead of generic ones (like :rst:role:`ref`). Example call:: - app.add_crossref_type('topic', 'topic', 'single: %s', docutils.nodes.emphasis) + app.add_crossref_type('topic', 'topic', 'single: %s', + docutils.nodes.emphasis) Example usage:: @@ -276,7 +312,7 @@ package. The application API ------------------- - <...> + Some random text here. See also :topic:`this section `. @@ -285,25 +321,33 @@ package. .. method:: Sphinx.add_transform(transform) - Add the standard docutils :class:`Transform` subclass *transform* to the list - of transforms that are applied after Sphinx parses a reST document. + Register a Docutils transform to be applied after parsing. + + Add the standard docutils :class:`Transform` subclass *transform* to the + list of transforms that are applied after Sphinx parses a reST document. .. method:: Sphinx.add_post_transform(transform) - Add the standard docutils :class:`Transform` subclass *transform* to the list - of transforms that are applied before Sphinx writes a document. + Register a Docutils transform to be applied before writing. + + Add the standard docutils :class:`Transform` subclass *transform* to the + list of transforms that are applied before Sphinx writes a document. .. method:: 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 `. A full URI with - scheme, like ``http://example.org/foo.js``, is also supported. + 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, see :confval:`the docs for the config value `. A + full URI with scheme, like ``http://example.org/foo.js``, is also supported. .. versionadded:: 0.5 .. method:: Sphinx.add_stylesheet(filename, alternate=None, title=None) + Register a stylesheet to include in the HTML output. + Add *filename* to the list of CSS files that the default HTML template will include. Like for :meth:`add_javascript`, the filename must be relative to the HTML static path, or a full URI with scheme. @@ -313,23 +357,31 @@ package. .. versionchanged:: 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`` (see `this explanation - `_). + default is no title and *alternate* = ``False``. Refer to the + `documentation `__ for + more information. .. method:: Sphinx.add_latex_package(packagename, options=None) - Add *packagename* to the list of packages that LaTeX source code will include. - If you provide *options*, it will be taken to `\usepackage` declaration. + 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. .. code-block:: python - app.add_latex_package('mypackage') # => \usepackage{mypackage} - app.add_latex_package('mypackage', 'foo,bar') # => \usepackage[foo,bar]{mypackage} + app.add_latex_package('mypackage') + # => \usepackage{mypackage} + app.add_latex_package('mypackage', 'foo,bar') + # => \usepackage[foo,bar]{mypackage} .. versionadded:: 1.3 .. method:: Sphinx.add_lexer(alias, lexer) + Register a new lexer for source code. + Use *lexer*, which must be an instance of a Pygments lexer class, to highlight code blocks with the given language *alias*. @@ -337,30 +389,37 @@ package. .. method:: Sphinx.add_autodocumenter(cls) + Register a new documenter class for the autodoc extension. + Add *cls* as a new documenter class for the :mod:`sphinx.ext.autodoc` extension. It must be a subclass of :class:`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 :class:`Documenter`. - .. XXX add real docs for Documenter and subclassing + .. todo:: Add real docs for Documenter and subclassing .. versionadded:: 0.6 .. method:: 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 - :func:`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 :func:`getattr`. + :func:`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 :func:`getattr`. .. versionadded:: 0.6 .. method:: Sphinx.add_search_language(cls) - Add *cls*, which must be a subclass of :class:`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 :confval:`html_search_language`. + Register a new language for the HTML search index. + + Add *cls*, which must be a subclass of + :class:`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 + :confval:`html_search_language`. .. versionadded:: 1.1 @@ -379,30 +438,35 @@ package. .. method:: Sphinx.add_env_collector(collector) - Register an environment collector class (refs: :ref:`collector-api`) + Register an environment collector class + + Refer to :ref:`collector-api`. .. versionadded:: 1.6 .. method:: 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. + 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. .. versionadded:: 1.0 .. method:: 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 - :ref:`events`. + Register *callback* to be called when *event* is emitted. + + For details on available core events and the arguments of callback + functions, please see :ref:`events`. The method returns a "listener ID" that can be used as an argument to :meth:`disconnect`. .. method:: Sphinx.disconnect(listener_id) - Unregister callback *listener_id*. + Unregister callback by *listener_id*. .. exception:: ExtensionError @@ -416,14 +480,16 @@ Emitting events .. method:: 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 *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! .. method:: 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``. + Emit *event* and pass *arguments* to the callback functions. + + Return the result of the first callback that doesn't return ``None``. .. versionadded:: 0.5 @@ -682,8 +748,11 @@ Use this to adapt your extension to API changes in Sphinx. .. data:: version_info + 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)``. + ``(1, 2, 1, 'beta', 3)``. The fourth element can be one of: ``alpha``, + ``beta``, ``rc``, ``final``. ``final`` always has 0 as the last element. .. versionadded:: 1.2 Before version 1.2, check the string ``sphinx.__version__``.