doc: Rework 'sphinx.application' API documentation

Signed-off-by: Stephen Finucane <stephen@that.guru>

1 files changed, 161 insertions, 92 deletions

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.
 
-   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`.
+   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.
+
+   *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*,
+   - 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
      <http://docutils.sourceforge.net/docs/howto/rst-directives.html>`_ 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
-   <http://docutils.sourceforge.net/docs/howto/rst-roles.html>`_ 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
+   <http://docutils.sourceforge.net/docs/howto/rst-roles.html>`_ 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 <application API>`.
 
@@ -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 <html_static_path>`.  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 <html_static_path>`.  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
-      <https://developer.mozilla.org/en-US/docs/Web/CSS/Alternative_style_sheets>`_).
+      default is no title and *alternate* = ``False``. Refer to the
+      `documentation <https://mdn.io/Web/CSS/Alternative_style_sheets>`__ 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__``.