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.