diff options
Diffstat (limited to 'doc/ext')
| -rw-r--r-- | doc/ext/appapi.rst | 16 | ||||
| -rw-r--r-- | doc/ext/autodoc.rst | 18 | ||||
| -rw-r--r-- | doc/ext/builderapi.rst | 8 | ||||
| -rw-r--r-- | doc/ext/doctest.rst | 8 |
4 files changed, 47 insertions, 3 deletions
diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst index fcc29e38..00fd2e58 100644 --- a/doc/ext/appapi.rst +++ b/doc/ext/appapi.rst @@ -13,7 +13,7 @@ the following public API: .. method:: Sphinx.add_builder(builder) Register a new builder. *builder* must be a class that inherits from - :class:`~sphinx.builder.Builder`. + :class:`~sphinx.builders.Builder`. .. method:: Sphinx.add_config_value(name, default, rebuild_env) @@ -86,6 +86,13 @@ the following public API: source, *role* the role function (see the `Docutils documentation <http://docutils.sourceforge.net/docs/howto/rst-roles.html>`_ on details). +.. method:: Sphinx.add_generic_role(name, nodeclass) + + Register a Docutils role that does nothing but wrap its contents in the + node given by *nodeclass*. + + .. versionadded:: 0.6 + .. method:: Sphinx.add_description_unit(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None) This method is a very convenient way to add a new type of information that @@ -167,6 +174,13 @@ the following public API: :confval:`the docs for the config value <html_static_path>`. .. versionadded:: 0.5 + +.. method:: Sphinx.add_lexer(alias, lexer) + + Use *lexer*, which must be an instance of a Pygments lexer class, to + highlight code blocks with the given language *alias*. + + .. versionadded:: 0.6 .. method:: Sphinx.connect(event, callback) diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index 3e5ce3e1..3b2cdb54 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -142,12 +142,30 @@ directive. .. directive:: autofunction + autodata automethod autoattribute These work exactly like :dir:`autoclass` etc., but do not offer the options used for automatic member documentation. + For module data members and class attributes, documentation can either be put + into a special-formatted comment *before* the attribute definition, or in a + docstring *after* the definition. This means that in the following class + definition, both attributes can be autodocumented:: + + class Foo: + """Docstring for class Foo.""" + + #: Doc comment for attribute Foo.bar. + bar = 1 + + baz = 2 + """Docstring for attribute Foo.baz.""" + + .. versionchanged:: 0.6 + :dir:`autodata` and :dir:`autoattribute` can now extract docstrings. + .. note:: If you document decorated functions or methods, keep in mind that autodoc diff --git a/doc/ext/builderapi.rst b/doc/ext/builderapi.rst index adc41016..5c671f2d 100644 --- a/doc/ext/builderapi.rst +++ b/doc/ext/builderapi.rst @@ -5,7 +5,7 @@ Writing new builders .. todo:: Expand this. -.. currentmodule:: sphinx.builder +.. currentmodule:: sphinx.builders .. class:: Builder @@ -20,7 +20,7 @@ Writing new builders .. automethod:: build_update .. automethod:: build - These methods must be overridden in concrete builder classes: + These methods can be overridden in concrete builder classes: .. automethod:: init .. automethod:: get_outdated_docs @@ -28,3 +28,7 @@ Writing new builders .. automethod:: prepare_writing .. automethod:: write_doc .. automethod:: finish + + Useful helpers: + + .. automethod:: init_templates diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst index 9de6ba9e..7117f6a9 100644 --- a/doc/ext/doctest.rst +++ b/doc/ext/doctest.rst @@ -149,6 +149,14 @@ There are also these config values for customizing the doctest extension: A list of directories that will be added to :data:`sys.path` when the doctest builder is used. (Make sure it contains absolute paths.) +.. confval:: doctest_global_setup + + Python code that is treated like it were put in a ``testsetup`` directive for + *every* file that is tested, and for every group. You can use this to + e.g. import modules you will always need in your doctests. + + .. versionadded:: 0.6 + .. confval:: doctest_test_doctest_blocks If this is a nonempty string (the default is ``'default'``), standard reST |