From c3b8e3fdf0085a6848dcaae5f3f112ef28025716 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 9 Sep 2009 18:26:59 +0200 Subject: [PATCH 1/4] Clarify docs of automodule options. --- doc/ext/autodoc.rst | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index bd1551add..f67b8a8a6 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -72,21 +72,27 @@ directive. * If you want to automatically document members, there's a ``members`` option:: + .. automodule:: noodle + :members: + + will document all module members (recursively), and + .. autoclass:: Noodle :members: will document all non-private member functions and properties (that is, - those whose name doesn't start with ``_``), while :: + those whose name doesn't start with ``_``). + + You can also give an explicit list of members; only these will then be + documented:: .. autoclass:: Noodle :members: eat, slurp - will document exactly the specified members. - * Members without docstrings will be left out, unless you give the ``undoc-members`` flag option:: - .. autoclass:: Noodle + .. automodule:: noodle :members: :undoc-members: @@ -141,11 +147,11 @@ directive. .. versionadded:: 0.6 - * The directives supporting member documentation also have a - ``exclude-members`` option that can be used to exclude single member names - from documentation, if all members are to be documented. + * The directives supporting member documentation also have a + ``exclude-members`` option that can be used to exclude single member names + from documentation, if all members are to be documented. - .. versionadded:: 0.6 + .. versionadded:: 0.6 .. note:: From 87cf9675c8730432f4500dbfa6434e511a83d4c9 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 9 Sep 2009 18:27:59 +0200 Subject: [PATCH 2/4] Fix markup. --- doc/ext/autodoc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index f67b8a8a6..9a6b1dfa1 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -75,7 +75,7 @@ directive. .. automodule:: noodle :members: - will document all module members (recursively), and + will document all module members (recursively), and :: .. autoclass:: Noodle :members: From 290a62366988c0c63862944ca00aa930a5e7837d Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 9 Sep 2009 19:10:24 +0200 Subject: [PATCH 3/4] Note that member docstrings need to be reST as well. --- doc/ext/autodoc.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index 9a6b1dfa1..b4b4b3f31 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -107,6 +107,9 @@ directive. This can be combined with ``undoc-members`` to document *all* available members of the class or module. + Note: this will lead to markup errors if the inherited members come from a + module whose docstrings are not reST formatted. + .. versionadded:: 0.3 * It's possible to override the signature for explicitly documented callable From 66c254c582626a5b7f00519faeddcc1049a95296 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 9 Sep 2009 19:18:02 +0200 Subject: [PATCH 4/4] copy over autosummary docs from trunk. --- doc/ext/autosummary.rst | 218 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 217 insertions(+), 1 deletion(-) diff --git a/doc/ext/autosummary.rst b/doc/ext/autosummary.rst index a9255857b..57abd6165 100644 --- a/doc/ext/autosummary.rst +++ b/doc/ext/autosummary.rst @@ -6,4 +6,220 @@ .. module:: sphinx.ext.autosummary :synopsis: Generate autodoc summaries -TBW. +.. versionadded:: 0.6 + +This extension generates function/method/attribute summary lists, similar to +those output e.g. by Epydoc and other API doc generation tools. This is +especially useful when your docstrings are long and detailed, and putting each +one of them on a separate page makes them easier to read. + +The :mod:`sphinx.ext.autosummary` extension does this in two parts: + +1. There is an :dir:`autosummary` directive for generating summary listings that + contain links to the documented items, and short summary blurbs extracted + from their docstrings. + +2. The convenience script :program:`sphinx-autogen` or the new + :confval:`autosummary_generate` config value can be used to generate short + "stub" files for the entries listed in the :dir:`autosummary` directives. + These by default contain only the corresponding :mod:`sphinx.ext.autodoc` + directive. + + +.. directive:: autosummary + + Insert a table that contains links to documented items, and a short summary + blurb (the first sentence of the docstring) for each of them. The + :dir:`autosummary` directive can also optionally serve as a :dir:`toctree` + entry for the included items. + + For example, :: + + .. currentmodule:: sphinx + + .. autosummary:: + + environment.BuildEnvironment + util.relative_uri + + produces a table like this: + + .. currentmodule:: sphinx + + .. autosummary:: + + environment.BuildEnvironment + util.relative_uri + + .. currentmodule:: sphinx.ext.autosummary + + Autosummary preprocesses the docstrings and signatures with the same + :event:`autodoc-process-docstring` and :event:`autodoc-process-signature` + hooks as :mod:`~sphinx.ext.autodoc`. + + + **Options** + + * If you want the :dir:`autosummary` table to also serve as a :dir:`toctree` + entry, use the ``toctree`` option, for example:: + + .. autosummary:: + :toctree: DIRNAME + + sphinx.environment.BuildEnvironment + sphinx.util.relative_uri + + The ``toctree`` option also signals to the :program:`sphinx-autogen` script + that stub pages should be generated for the entries listed in this + directive. The option accepts a directory name as an argument; + :program:`sphinx-autogen` will by default place its output in this + directory. If no argument is given, output is placed in the same directory + as the file that contains the directive. + + * If you don't want the :dir:`autosummary` to show function signatures in the + listing, include the ``nosignatures`` option:: + + .. autosummary:: + :nosignatures: + + sphinx.environment.BuildEnvironment + sphinx.util.relative_uri + + * You can specify a custom template with the ``template`` option. + For example, :: + + .. autosummary:: + :template: mytemplate.rst + + sphinx.environment.BuildEnvironment + + would use the template :file:`mytemplate.rst` in your + :confval:`templates_path` to generate the pages for all entries + listed. See `Customizing templates`_ below. + + +:program:`sphinx-autogen` -- generate autodoc stub pages +-------------------------------------------------------- + +The :program:`sphinx-autogen` script can be used to conveniently generate stub +documentation pages for items included in :dir:`autosummary` listings. + +For example, the command :: + + $ sphinx-autogen -o generated *.rst + +will read all :dir:`autosummary` tables in the :file:`*.rst` files that have the +``:toctree:`` option set, and output corresponding stub pages in directory +``generated`` for all documented items. The generated pages by default contain +text of the form:: + + sphinx.util.relative_uri + ======================== + + .. autofunction:: sphinx.util.relative_uri + +If the ``-o`` option is not given, the script will place the output files in the +directories specified in the ``:toctree:`` options. + + +Generating stub pages automatically +----------------------------------- + +If you do not want to create stub pages with :program:`sphinx-autogen`, you can +also use this new config value: + +.. confval:: autosummary_generate + + Boolean indicating whether to scan all found documents for autosummary + directives, and to generate stub pages for each. + + Can also be a list of documents for which stub pages should be generated. + + The new files will be placed in the directories specified in the + ``:toctree:`` options of the directives. + + +Customizing templates +--------------------- + +You can customize the stub page templates, in a similar way as the HTML Jinja +templates, see :ref:`templating`. (:class:`~sphinx.application.TemplateBridge` +is not supported.) + +.. note:: + + If you find yourself spending much time tailoring the stub templates, this + may indicate that it's a better idea to write custom narrative documentation + instead. + +Autosummary uses the following template files: + +- :file:`autosummary/base.rst` -- fallback template +- :file:`autosummary/module.rst` -- template for modules +- :file:`autosummary/class.rst` -- template for classes +- :file:`autosummary/function.rst` -- template for functions +- :file:`autosummary/attribute.rst` -- template for class attributes +- :file:`autosummary/method.rst` -- template for class methods + +The following variables available in the templates: + +.. data:: name + + Name of the documented object, excluding the module and class parts. + +.. data:: objname + + Name of the documented object, excluding the module parts. + +.. data:: fullname + + Full name of the documented object, including module and class parts. + +.. data:: module + + Name of the module the documented object belongs to. + +.. data:: class + + Name of the class the documented object belongs to. Only available for + methods and attributes. + +.. data:: underline + + A string containing ``len(full_name) * '='``. + +.. data:: members + + List containing names of all members of the module or class. Only available + for modules and classes. + +.. data:: functions + + List containing names of "public" functions in the module. Here, "public" + here means that the name does not start with an underscore. Only available + for modules. + +.. data:: classes + + List containing names of "public" classes in the module. Only available for + modules. + +.. data:: exceptions + + List containing names of "public" exceptions in the module. Only available + for modules. + +.. data:: methods + + List containing names of "public" methods in the class. Only available for + classes. + +.. data:: methods + + List containing names of "public" attributes in the class. Only available + for classes. + +.. note:: + + You can use the :dir:`autosummary` directive in the stub pages. + Stub pages are generated also based on these directives.