From eaaab75ec2ab72566176fec9a328d473fbd5f1ee Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Sat, 20 Jan 2018 22:47:42 +0000 Subject: [PATCH 1/5] doc: Rework 'sphinx.application' API documentation Signed-off-by: Stephen Finucane --- doc/extdev/appapi.rst | 253 +++++++++++++++++++++++++++--------------- 1 file 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. 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__``. From b7ff95547275e77b311f5bb04a7bc9e7c810c0e5 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Sun, 22 Oct 2017 14:59:09 +0100 Subject: [PATCH 2/5] doc: Move 'sphinx.application' API docs to code This allows us to do something like 'help(sphinx.application)' in code. Signed-off-by: Stephen Finucane --- doc/extdev/appapi.rst | 476 ++++-------------------------------------- sphinx/__init__.py | 11 +- sphinx/application.py | 421 ++++++++++++++++++++++++++++++++++++- 3 files changed, 464 insertions(+), 444 deletions(-) diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index 607155544..8be2560e9 100644 --- a/doc/extdev/appapi.rst +++ b/doc/extdev/appapi.rst @@ -7,9 +7,9 @@ Application API :synopsis: Application class and extensibility interface. -Each Sphinx extension is a Python module with at least a :func:`setup` function. -This function is called at initialization time with one argument, the -application object representing the Sphinx process. +Each Sphinx extension is a Python module with at least a :func:`setup` +function. This function is called at initialization time with one argument, +the application object representing the Sphinx process. .. class:: Sphinx @@ -23,451 +23,73 @@ These methods are usually called in an extension's ``setup()`` function. Examples of using the Sphinx extension API can be seen in the :mod:`sphinx.ext` package. -.. method:: Sphinx.setup_extension(name) +.. currentmodule:: sphinx.application - Import and setup a Sphinx extension module. +.. automethod:: Sphinx.setup_extension(name) - 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. +.. automethod:: Sphinx.add_builder(builder) -.. method:: Sphinx.add_builder(builder) +.. automethod:: Sphinx.add_config_value(name, default, rebuild) - Register a new builder. +.. automethod:: Sphinx.add_domain(domain) - *builder* must be a class that inherits from - :class:`~sphinx.builders.Builder`. +.. automethod:: Sphinx.override_domain(domain) -.. method:: Sphinx.add_config_value(name, default, rebuild) +.. automethod:: Sphinx.add_index_to_domain(domain, index) - Register a configuration value. +.. automethod:: Sphinx.add_event(name) - 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: +.. automethod:: Sphinx.set_translator(name, translator_class) - * ``'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. +.. automethod:: Sphinx.add_node(node, \*\*kwds) - .. 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) - - 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) - - 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`. - - .. versionadded:: 1.0 - -.. method:: Sphinx.add_event(name) - - Register an event called *name*. This is needed to be able to emit it. - -.. 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`). - - .. versionadded:: 1.3 - -.. 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. - - 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 - :exc:`docutils.nodes.SkipNode`. Example: - - .. code-block:: python - - 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('') - - 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. - - .. versionchanged:: 0.5 - Added the support for keyword arguments giving visit functions. - -.. 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`. - - *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 :rst:role:`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 - :meth:`Sphinx.add_node` for details. - - .. versionadded:: 1.4 +.. automethod:: Sphinx.add_enumerable_node(node, figtype, title_getter=None, \*\*kwds) .. 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: - - - 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 must inherit from the class - ``docutils.parsers.rst.Directive``. - - For example, the (already existing) :rst:dir:`literalinclude` directive - would be added like this: - - .. code-block:: python - - from docutils.parsers.rst import directives - add_directive('literalinclude', literalinclude_directive, - content = 0, arguments = (1, 0, 0), - linenos = directives.flag, - language = directives.unchanged, - encoding = directives.encoding) - - .. versionchanged:: 0.6 - Docutils 0.5-style directive classes are now supported. +.. automethod:: Sphinx.add_directive(name, directiveclass) .. method:: Sphinx.add_directive_to_domain(domain, name, func, content, arguments, \*\*options) - Sphinx.add_directive_to_domain(domain, name, directiveclass) +.. automethod:: Sphinx.add_directive_to_domain(domain, name, directiveclass) - Register a Docutils directive in a domain. +.. automethod:: Sphinx.add_role(name, role) - Like :meth:`add_directive`, but the directive is added to the domain named - *domain*. +.. automethod:: Sphinx.add_role_to_domain(domain, name, role) - .. versionadded:: 1.0 +.. automethod:: Sphinx.add_generic_role(name, nodeclass) -.. method:: Sphinx.add_role(name, role) +.. automethod:: Sphinx.add_object_type(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None, objname='', doc_field_types=[]) - Register a Docutils role. +.. automethod:: Sphinx.add_crossref_type(directivename, rolename, indextemplate='', ref_nodeclass=None, objname='') - *name* must be the role name that occurs in the source, *role* the role - function. Refer to the `Docutils documentation - `_ for more - information. +.. automethod:: Sphinx.add_transform(transform) -.. method:: Sphinx.add_role_to_domain(domain, name, role) +.. automethod:: Sphinx.add_post_transform(transform) - Register a Docutils role in a domain. +.. automethod:: Sphinx.add_javascript(filename) - Like :meth:`add_role`, but the role is added to the domain named *domain*. +.. automethod:: Sphinx.add_stylesheet(filename, alternate=None, title=None) - .. versionadded:: 1.0 +.. automethod:: Sphinx.add_latex_package(packagename, options=None) -.. method:: Sphinx.add_generic_role(name, nodeclass) +.. automethod:: Sphinx.add_lexer(alias, lexer) - Register a generic Docutils role. +.. automethod:: Sphinx.add_autodocumenter(cls) - Register a Docutils role that does nothing but wrap its contents in the node - given by *nodeclass*. +.. automethod:: Sphinx.add_autodoc_attrgetter(type, getter) - Don't use ``roles.register_generic_role`` because it uses - ``register_canonical_role``. +.. automethod:: Sphinx.add_search_language(cls) - .. versionadded:: 0.6 +.. automethod:: Sphinx.add_source_parser(suffix, parser) -.. method:: Sphinx.add_object_type(directivename, rolename, indextemplate='', parse_node=None, \ - ref_nodeclass=None, objname='', doc_field_types=[]) +.. automethod:: Sphinx.add_html_theme(name, theme_path) - Register a new object type. +.. automethod:: Sphinx.add_env_collector(collector) - This method is a very convenient way to add a new :term:`object` type that - can be cross-referenced. It will do this: +.. automethod:: Sphinx.require_sphinx(version) - - 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 :file:`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 :ref:`xref-syntax`). - - This method is also available under the deprecated alias - :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. - - That means that you can add semantic targets to your sources, and refer to - 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) - - Example usage:: - - .. topic:: application API - - The application API - ------------------- - - Some random text here. - - See also :topic:`this section `. - - (Of course, the element following the ``topic`` directive needn't be a - section.) - -.. method:: Sphinx.add_transform(transform) - - 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) - - 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) - - 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. - - .. versionadded:: 1.0 - - .. 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``. Refer to the - `documentation `__ for - more information. - -.. method:: 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. - - .. code-block:: python - - 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*. - - .. versionadded:: 0.6 - -.. 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`. - - .. 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 *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) - - 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 - -.. method:: Sphinx.add_source_parser(suffix, parser) - - Register a parser class for specified *suffix*. - - .. versionadded:: 1.4 - -.. method:: 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: :ref:`distribute-your-theme`). - - .. versionadded:: 1.6 - -.. method:: Sphinx.add_env_collector(collector) - - Register an environment collector class - - Refer to :ref:`collector-api`. - - .. versionadded:: 1.6 - -.. method:: 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. - - .. 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`. - - The method returns a "listener ID" that can be used as an argument to - :meth:`disconnect`. - -.. method:: Sphinx.disconnect(listener_id) - - Unregister callback by *listener_id*. +.. automethod:: Sphinx.connect(event, callback) +.. automethod:: Sphinx.disconnect(listener_id) .. exception:: ExtensionError @@ -478,20 +100,11 @@ package. Emitting events --------------- -.. method:: Sphinx.emit(event, *arguments) +.. class:: Sphinx - Emit *event* and pass *arguments* to the callback functions. + .. automethod:: emit(event, \*arguments) - 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``. - - .. versionadded:: 0.5 + .. automethod:: emit_firstresult(event, \*arguments) Producing messages / logging @@ -746,16 +359,7 @@ Checking the Sphinx version 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)``. 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__``. +.. autodata:: version_info The Config object diff --git a/sphinx/__init__.py b/sphinx/__init__.py index 6781537f6..3cc84a5ca 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -34,9 +34,14 @@ warnings.filterwarnings('ignore', "'U' mode is deprecated", __version__ = '1.8.0+' __released__ = '1.8.0' # used when Sphinx builds its own docs -# version info for better programmatic use -# possible values for 3rd element: 'alpha', 'beta', 'rc', 'final' -# 'final' has 0 as the last element +#: 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. +#: +#: .. versionadded:: 1.2 +#: Before version 1.2, check the string ``sphinx.__version__``. version_info = (1, 8, 0, 'beta', 0) package_dir = path.abspath(path.dirname(__file__)) diff --git a/sphinx/application.py b/sphinx/application.py index c5e512ff5..dec5ce19b 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -3,7 +3,7 @@ sphinx.application ~~~~~~~~~~~~~~~~~~ - Sphinx application object. + Sphinx application class and extensibility interface. Gracefully adapted from the TextPress system by Armin. @@ -111,6 +111,13 @@ logger = logging.getLogger(__name__) class Sphinx(object): + """The main application class and extensibility interface. + + :ivar srcdir: Directory containing source. + :ivar confdir: Directory containing ``conf.py``. + :ivar doctreedir: Directory for storing pickled doctrees. + :ivar outdir: Directory for storing build documents. + """ def __init__(self, srcdir, confdir, outdir, doctreedir, buildername, confoverrides=None, status=sys.stdout, warning=sys.stderr, @@ -424,13 +431,25 @@ class Sphinx(object): def setup_extension(self, extname): # type: (unicode) -> None - """Import and setup a Sphinx extension module. No-op if called twice.""" + """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. + """ logger.debug('[app] setting up extension: %r', extname) self.registry.load_extension(self, extname) def require_sphinx(self, version): # type: (unicode) -> None - # check the Sphinx version if requested + """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 + """ if version > sphinx.__display_version__[:3]: raise VersionRequirementError(version) @@ -442,17 +461,31 @@ class Sphinx(object): # event interface def connect(self, event, callback): # type: (unicode, Callable) -> int + """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`. + """ listener_id = self.events.connect(event, callback) logger.debug('[app] connecting event %r: %r [id=%s]', event, callback, listener_id) return listener_id def disconnect(self, listener_id): # type: (int) -> None + """Unregister callback by *listener_id*.""" logger.debug('[app] disconnecting event: [id=%s]', listener_id) self.events.disconnect(listener_id) def emit(self, event, *args): # type: (unicode, Any) -> List + """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! + """ try: logger.debug('[app] emitting event: %r%s', event, repr(args)[:100]) except Exception: @@ -463,16 +496,53 @@ class Sphinx(object): def emit_firstresult(self, event, *args): # type: (unicode, Any) -> Any + """Emit *event* and pass *arguments* to the callback functions. + + Return the result of the first callback that doesn't return ``None``. + + .. versionadded:: 0.5 + """ return self.events.emit_firstresult(event, self, *args) # registering addon parts def add_builder(self, builder): # type: (Type[Builder]) -> None + """Register a new builder. + + *builder* must be a class that inherits from + :class:`~sphinx.builders.Builder`. + """ self.registry.add_builder(builder) + # TODO(stephenfin): Describe 'types' parameter def add_config_value(self, name, default, rebuild, types=()): # type: (unicode, Any, Union[bool, unicode], Any) -> None + """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. + + .. 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. + """ logger.debug('[app] adding config value: %r', (name, default, rebuild) + ((types,) if types else ())) # type: ignore if name in self.config: @@ -483,15 +553,56 @@ class Sphinx(object): def add_event(self, name): # type: (unicode) -> None + """Register an event called *name*. + + This is needed to be able to emit it. + """ logger.debug('[app] adding event: %r', name) self.events.add(name) def set_translator(self, name, translator_class): # type: (unicode, Type[nodes.NodeVisitor]) -> 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 custom translator + and define custom nodes for the translator (see :meth:`add_node`). + + .. versionadded:: 1.3 + """ self.registry.add_translator(name, translator_class) def add_node(self, node, **kwds): # type: (nodes.Node, Any) -> 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. + + 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 :exc:`docutils.nodes.SkipNode`. Example: + + .. code-block:: python + + 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('') + + 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. + + .. versionchanged:: 0.5 + Added the support for keyword arguments giving visit functions. + """ logger.debug('[app] adding node: %r', (node, kwds)) if not kwds.pop('override', False) and \ hasattr(nodes.GenericNodeVisitor, 'visit_' + node.__name__): @@ -536,11 +647,72 @@ class Sphinx(object): def add_enumerable_node(self, node, figtype, title_getter=None, **kwds): # type: (nodes.Node, unicode, Callable, Any) -> None + """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. + + *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 + :rst:role:`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 + :meth:`Sphinx.add_node` for details. + + .. versionadded:: 1.4 + """ self.enumerable_nodes[node] = (figtype, title_getter) self.add_node(node, **kwds) + # TODO(stephenfin): Remove docutils 0.4 style parsing and update the + # example to use the newer style def add_directive(self, name, obj, content=None, arguments=None, **options): # type: (unicode, Any, bool, Tuple[int, int, bool], Any) -> None + """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 must inherit from the class + ``docutils.parsers.rst.Directive``. + + For example, the (already existing) :rst:dir:`literalinclude` directive + would be added like this: + + .. code-block:: python + + from docutils.parsers.rst import directives + add_directive('literalinclude', literalinclude_directive, + content = 0, arguments = (1, 0, 0), + linenos = directives.flag, + language = directives.unchanged, + encoding = directives.encoding) + + .. versionchanged:: 0.6 + Docutils 0.5-style directive classes are now supported. + """ logger.debug('[app] adding directive: %r', (name, obj, content, arguments, options)) if name in directives._directives: @@ -553,6 +725,13 @@ class Sphinx(object): def add_role(self, name, role): # type: (unicode, Any) -> None + """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. + """ logger.debug('[app] adding role: %r', (name, role)) if name in roles._roles: logger.warning(__('while setting up extension %s: role %r is ' @@ -563,8 +742,15 @@ class Sphinx(object): def add_generic_role(self, name, nodeclass): # type: (unicode, Any) -> None - # don't use roles.register_generic_role because it uses - # register_canonical_role + """Register a generic Docutils role. + + Register a Docutils role that does nothing but wrap its contents in the + node given by *nodeclass*. + + .. versionadded:: 0.6 + """ + # Don't use ``roles.register_generic_role`` because it uses + # ``register_canonical_role``. logger.debug('[app] adding generic role: %r', (name, nodeclass)) if name in roles._roles: logger.warning(__('while setting up extension %s: role %r is ' @@ -576,30 +762,121 @@ class Sphinx(object): def add_domain(self, domain): # type: (Type[Domain]) -> None + """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 + """ self.registry.add_domain(domain) def override_domain(self, domain): # type: (Type[Domain]) -> None + """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 + """ self.registry.override_domain(domain) def add_directive_to_domain(self, domain, name, obj, has_content=None, argument_spec=None, **option_spec): # type: (unicode, unicode, Any, bool, Any, Any) -> None + """Register a Docutils directive in a domain. + + Like :meth:`add_directive`, but the directive is added to the domain + named *domain*. + + .. versionadded:: 1.0 + """ self.registry.add_directive_to_domain(domain, name, obj, has_content, argument_spec, **option_spec) def add_role_to_domain(self, domain, name, role): # type: (unicode, unicode, Union[RoleFunction, XRefRole]) -> None + """Register a Docutils role in a domain. + + Like :meth:`add_role`, but the role is added to the domain named + *domain*. + + .. versionadded:: 1.0 + """ self.registry.add_role_to_domain(domain, name, role) def add_index_to_domain(self, domain, index): # type: (unicode, Type[Index]) -> None + """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`. + + .. versionadded:: 1.0 + """ self.registry.add_index_to_domain(domain, index) def add_object_type(self, directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None, objname='', doc_field_types=[]): # type: (unicode, unicode, unicode, Callable, nodes.Node, unicode, List) -> None + """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. 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 + :file:`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 :ref:`xref-syntax`). + + This method is also available under the deprecated alias + :meth:`add_description_unit`. + """ self.registry.add_object_type(directivename, rolename, indextemplate, parse_node, ref_nodeclass, objname, doc_field_types) @@ -616,19 +893,67 @@ class Sphinx(object): def add_crossref_type(self, directivename, rolename, indextemplate='', ref_nodeclass=None, objname=''): # type: (unicode, unicode, unicode, nodes.Node, unicode) -> None + """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. + + That means that you can add semantic targets to your sources, and refer + to 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) + + Example usage:: + + .. topic:: application API + + The application API + ------------------- + + Some random text here. + + See also :topic:`this section `. + + (Of course, the element following the ``topic`` directive needn't be a + section.) + """ self.registry.add_crossref_type(directivename, rolename, indextemplate, ref_nodeclass, objname) def add_transform(self, transform): # type: (Type[Transform]) -> None + """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. + """ self.registry.add_transform(transform) def add_post_transform(self, transform): # type: (Type[Transform]) -> None + """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. + """ self.registry.add_post_transform(transform) def add_javascript(self, filename): # type: (unicode) -> None + """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 + """ logger.debug('[app] adding javascript: %r', filename) from sphinx.builders.html import StandaloneHTMLBuilder if '://' in filename: @@ -639,6 +964,21 @@ class Sphinx(object): def add_stylesheet(self, filename, alternate=False, title=None): # type: (unicode, bool, unicode) -> 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. + + .. versionadded:: 1.0 + + .. 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``. For + more information, refer to the `documentation + `__. + """ logger.debug('[app] adding stylesheet: %r', filename) from sphinx.builders.html import StandaloneHTMLBuilder, Stylesheet if '://' not in filename: @@ -652,12 +992,34 @@ class Sphinx(object): def add_latex_package(self, packagename, options=None): # type: (unicode, unicode) -> None + r"""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} + + .. versionadded:: 1.3 + """ logger.debug('[app] adding latex package: %r', packagename) if hasattr(self.builder, 'usepackages'): # only for LaTeX builder self.builder.usepackages.append((packagename, options)) # type: ignore def add_lexer(self, alias, lexer): # type: (unicode, Any) -> None + """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*. + + .. versionadded:: 0.6 + """ logger.debug('[app] adding lexer: %r', (alias, lexer)) from sphinx.highlighting import lexers if lexers is None: @@ -666,6 +1028,18 @@ class Sphinx(object): def add_autodocumenter(self, cls): # type: (Any) -> None + """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`. + + .. todo:: Add real docs for Documenter and subclassing + + .. versionadded:: 0.6 + """ logger.debug('[app] adding autodocumenter: %r', cls) from sphinx.ext.autodoc.directive import AutodocDirective self.registry.add_documenter(cls.objtype, cls) @@ -673,11 +1047,31 @@ class Sphinx(object): def add_autodoc_attrgetter(self, typ, getter): # type: (Type, Callable[[Any, unicode, 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 :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 + """ logger.debug('[app] adding autodoc attrgetter: %r', (typ, getter)) self.registry.add_autodoc_attrgetter(typ, getter) def add_search_language(self, cls): # type: (Any) -> None + """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 + """ logger.debug('[app] adding search language: %r', cls) from sphinx.search import languages, SearchLanguage assert issubclass(cls, SearchLanguage) @@ -685,15 +1079,32 @@ class Sphinx(object): def add_source_parser(self, suffix, parser): # type: (unicode, Parser) -> None + """Register a parser class for specified *suffix*. + + .. versionadded:: 1.4 + """ self.registry.add_source_parser(suffix, parser) def add_env_collector(self, collector): # type: (Type[EnvironmentCollector]) -> None + """Register an environment collector class. + + Refer to :ref:`collector-api`. + + .. versionadded:: 1.6 + """ logger.debug('[app] adding environment collector: %r', collector) collector().enable(self) def add_html_theme(self, name, theme_path): # type: (unicode, unicode) -> None + """Register a HTML Theme. + + The *name* is a name of theme, and *path* is a full path to the theme + (refs: :ref:`distribute-your-theme`). + + .. versionadded:: 1.6 + """ logger.debug('[app] adding HTML theme: %r, %r', name, theme_path) self.html_themes[name] = theme_path From 6c23dac5a66a479728610e960ac3c2002e5c033e Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Sun, 21 Jan 2018 10:55:30 +0000 Subject: [PATCH 3/5] doc: Reorder 'sphinx.application' docs to match code Use the same ordering to minimize cognitive load. Signed-off-by: Stephen Finucane --- doc/extdev/appapi.rst | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index 8be2560e9..b3d3c65de 100644 --- a/doc/extdev/appapi.rst +++ b/doc/extdev/appapi.rst @@ -27,16 +27,16 @@ package. .. automethod:: Sphinx.setup_extension(name) +.. automethod:: Sphinx.require_sphinx(version) + +.. automethod:: Sphinx.connect(event, callback) + +.. automethod:: Sphinx.disconnect(listener_id) + .. automethod:: Sphinx.add_builder(builder) .. automethod:: Sphinx.add_config_value(name, default, rebuild) -.. automethod:: Sphinx.add_domain(domain) - -.. automethod:: Sphinx.override_domain(domain) - -.. automethod:: Sphinx.add_index_to_domain(domain, index) - .. automethod:: Sphinx.add_event(name) .. automethod:: Sphinx.set_translator(name, translator_class) @@ -48,14 +48,20 @@ package. .. method:: Sphinx.add_directive(name, func, content, arguments, \*\*options) .. automethod:: Sphinx.add_directive(name, directiveclass) +.. automethod:: Sphinx.add_role(name, role) + +.. automethod:: Sphinx.add_generic_role(name, nodeclass) + +.. automethod:: Sphinx.add_domain(domain) + +.. automethod:: Sphinx.override_domain(domain) + .. method:: Sphinx.add_directive_to_domain(domain, name, func, content, arguments, \*\*options) .. automethod:: Sphinx.add_directive_to_domain(domain, name, directiveclass) -.. automethod:: Sphinx.add_role(name, role) - .. automethod:: Sphinx.add_role_to_domain(domain, name, role) -.. automethod:: Sphinx.add_generic_role(name, nodeclass) +.. automethod:: Sphinx.add_index_to_domain(domain, index) .. automethod:: Sphinx.add_object_type(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None, objname='', doc_field_types=[]) @@ -81,15 +87,9 @@ package. .. automethod:: Sphinx.add_source_parser(suffix, parser) -.. automethod:: Sphinx.add_html_theme(name, theme_path) - .. automethod:: Sphinx.add_env_collector(collector) -.. automethod:: Sphinx.require_sphinx(version) - -.. automethod:: Sphinx.connect(event, callback) - -.. automethod:: Sphinx.disconnect(listener_id) +.. automethod:: Sphinx.add_html_theme(name, theme_path) .. exception:: ExtensionError From 487480ca016e39a199853e5178e7f360bcb76587 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Sun, 21 Jan 2018 10:57:24 +0000 Subject: [PATCH 4/5] doc: Add 'is_parallel_allowed' This is an important function and should be documented. Signed-off-by: Stephen Finucane --- doc/extdev/appapi.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index b3d3c65de..129a6d228 100644 --- a/doc/extdev/appapi.rst +++ b/doc/extdev/appapi.rst @@ -91,6 +91,8 @@ package. .. automethod:: Sphinx.add_html_theme(name, theme_path) +.. automethod:: Sphinx.is_parallel_allowed(typ) + .. exception:: ExtensionError All these methods raise this exception if something went wrong with the From 1ec03ec1b034957956151f2e1c9e239428d38832 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Sun, 21 Jan 2018 11:15:20 +0000 Subject: [PATCH 5/5] doc: Add 'deprecated' directive to docstrings This helps emphasize the deprecated nature of these directives. Signed-off-by: Stephen Finucane --- sphinx/application.py | 40 +++++++++++++++++++++++++++++++++------- 1 file changed, 33 insertions(+), 7 deletions(-) diff --git a/sphinx/application.py b/sphinx/application.py index dec5ce19b..db4122b16 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -386,10 +386,15 @@ class Sphinx(object): # type: (unicode, unicode, unicode, unicode) -> None """Emit a warning. - If *location* is given, it should either be a tuple of (docname, lineno) - or a string describing the location of the warning as well as possible. + If *location* is given, it should either be a tuple of (*docname*, + *lineno*) or a string describing the location of the warning as well as + possible. - *type* and *subtype* are used to suppress warnings with :confval:`suppress_warnings`. + *type* and *subtype* are used to suppress warnings with + :confval:`suppress_warnings`. + + .. deprecated:: 1.6 + Use :mod:`sphinx.util.logging` instead. """ warnings.warn('app.warning() is now deprecated. Use sphinx.util.logging instead.', RemovedInSphinx20Warning) @@ -401,6 +406,9 @@ class Sphinx(object): If *nonl* is true, don't emit a newline at the end (which implies that more info output will follow soon.) + + .. deprecated:: 1.6 + Use :mod:`sphinx.util.logging` instead. """ warnings.warn('app.info() is now deprecated. Use sphinx.util.logging instead.', RemovedInSphinx20Warning) @@ -408,21 +416,33 @@ class Sphinx(object): def verbose(self, message, *args, **kwargs): # type: (unicode, Any, Any) -> None - """Emit a verbose informational message.""" + """Emit a verbose informational message. + + .. deprecated:: 1.6 + Use :mod:`sphinx.util.logging` instead. + """ warnings.warn('app.verbose() is now deprecated. Use sphinx.util.logging instead.', RemovedInSphinx20Warning) logger.verbose(message, *args, **kwargs) def debug(self, message, *args, **kwargs): # type: (unicode, Any, Any) -> None - """Emit a debug-level informational message.""" + """Emit a debug-level informational message. + + .. deprecated:: 1.6 + Use :mod:`sphinx.util.logging` instead. + """ warnings.warn('app.debug() is now deprecated. Use sphinx.util.logging instead.', RemovedInSphinx20Warning) logger.debug(message, *args, **kwargs) def debug2(self, message, *args, **kwargs): # type: (unicode, Any, Any) -> None - """Emit a lowlevel debug-level informational message.""" + """Emit a lowlevel debug-level informational message. + + .. deprecated:: 1.6 + Use :mod:`sphinx.util.logging` instead. + """ warnings.warn('app.debug2() is now deprecated. Use debug() instead.', RemovedInSphinx20Warning) logger.debug(message, *args, **kwargs) @@ -453,9 +473,10 @@ class Sphinx(object): if version > sphinx.__display_version__[:3]: raise VersionRequirementError(version) + # TODO(stephenfin): Deprecate this as it has no callers and isn't necessary def import_object(self, objname, source=None): # type: (str, unicode) -> Any - """Import an object from a 'module.name' string.""" + """Import an object from a ``module.name`` string.""" return import_object(objname, source=None) # event interface @@ -884,6 +905,11 @@ class Sphinx(object): parse_node=None, ref_nodeclass=None, objname='', doc_field_types=[]): # type: (unicode, unicode, unicode, Callable, nodes.Node, unicode, List) -> None + """Deprecated alias for :meth:`add_object_type`. + + .. deprecated:: 1.6 + Use :meth:`add_object_type` instead. + """ warnings.warn('app.add_description_unit() is now deprecated. ' 'Use app.add_object_type() instead.', RemovedInSphinx20Warning)