"sphinx.ext.autosummary" -- Generate autodoc summaries
******************************************************

New in version 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 "sphinx.ext.autosummary" extension does this in two parts:

1. There is an "autosummary" directive for generating summary listings
   that contain links to the documented items, and short summary
   blurbs extracted from their docstrings.

2. A "autosummary" directive also generates short "stub" files for the
   entries listed in its content.  These files by default contain only
   the corresponding "sphinx.ext.autodoc" directive, but can be
   customized with templates.

   The **sphinx-autogen** script is also able to generate "stub" files
   from command line.

.. 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 "autosummary" directive can also optionally serve as a
   "toctree" entry for the included items. Optionally, stub ".rst"
   files for these items can also be automatically generated when
   "autosummary_generate" is *True*.

   For example,

      .. currentmodule:: sphinx

      .. autosummary::

         environment.BuildEnvironment
         util.relative_uri

   produces a table like this:

   +------------+--------------------------------------------------------------------------------------------+
   | "environm  | The environment in which the ReST files are translated.                                    |
   | ent.Build  |                                                                                            |
   | Environme  |                                                                                            |
   | nt"(app)   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "util.rel  | Return a relative URL from "base" to "to".                                                 |
   | ative_uri  |                                                                                            |
   | "(base,    |                                                                                            |
   | to)        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   Autosummary preprocesses the docstrings and signatures with the
   same "autodoc-process-docstring" and "autodoc-process-signature"
   hooks as "autodoc".

   **Options**

   * If you want the "autosummary" table to also serve as a "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 **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; **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.

     You can also use "caption" option to give a caption to the
     toctree.

     New in version 3.1: caption option added.

   * If you don't want the "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 "mytemplate.rst" in your "templates_path"
     to generate the pages for all entries listed. See Customizing
     templates below.

     New in version 1.0.

   * You can specify the "recursive" option to generate documents for
     modules and sub-packages recursively.  It defaults to disabled.
     For example,

        .. autosummary::
           :recursive:

           sphinx.environment.BuildEnvironment

     New in version 3.1.


**sphinx-autogen** -- generate autodoc stub pages
=================================================

The **sphinx-autogen** script can be used to conveniently generate
stub documentation pages for items included in "autosummary" listings.

For example, the command

   $ sphinx-autogen -o generated *.rst

will read all "autosummary" tables in the "*.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.

For more information, refer to the sphinx-autogen documentation


Generating stub pages automatically
===================================

If you do not want to create stub pages with **sphinx-autogen**, you
can also use these config values:

autosummary_context

   A dictionary of values to pass into the template engine's context
   for autosummary stubs files.

   New in version 3.1.

autosummary_generate

   Boolean indicating whether to scan all found documents for
   autosummary directives, and to generate stub pages for each. It is
   enabled by default.

   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.

   Changed in version 2.3: Emits "autodoc-skip-member" event as
   "autodoc" does.

   Changed in version 4.0: Enabled by default.

autosummary_generate_overwrite

   If true, autosummary overwrites existing files by generated stub
   pages. Defaults to true (enabled).

   New in version 3.0.

autosummary_mock_imports

   This value contains a list of modules to be mocked up.  See
   "autodoc_mock_imports" for more details.  It defaults to
   "autodoc_mock_imports".

   New in version 2.0.

autosummary_imported_members

   A boolean flag indicating whether to document classes and functions
   imported in modules. Default is "False"

   New in version 2.1.

   Changed in version 4.4: If "autosummary_ignore_module_all" is
   "False", this configuration value is ignored for members listed in
   "__all__".

autosummary_ignore_module_all

   If "False" and a module has the "__all__" attribute set,
   autosummary documents every member listed in "__all__" and no
   others. Default is "True"

   Note that if an imported member is listed in "__all__", it will be
   documented regardless of the value of
   "autosummary_imported_members". To match the behaviour of "from
   module import *", set "autosummary_ignore_module_all" to False and
   "autosummary_imported_members" to True.

   New in version 4.4.

autosummary_filename_map

   A dict mapping object names to filenames. This is necessary to
   avoid filename conflicts where multiple objects have names that are
   indistinguishable when case is ignored, on file systems where
   filenames are case-insensitive.

   New in version 3.2.


Customizing templates
=====================

New in version 1.0.

You can customize the stub page templates, in a similar way as the
HTML Jinja templates, see Templating. ("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 Jinja template files:

* "autosummary/base.rst" -- fallback template

* "autosummary/module.rst" -- template for modules

* "autosummary/class.rst" -- template for classes

* "autosummary/function.rst" -- template for functions

* "autosummary/attribute.rst" -- template for class attributes

* "autosummary/method.rst" -- template for class methods

The following variables are available in the templates:

name

   Name of the documented object, excluding the module and class
   parts.

objname

   Name of the documented object, excluding the module parts.

fullname

   Full name of the documented object, including module and class
   parts.

objtype

   Type of the documented object, one of ""module"", ""function"",
   ""class"", ""method"", ""attribute"", ""data"", ""object"",
   ""exception"", ""newvarattribute"", ""newtypedata"", ""property"".

module

   Name of the module the documented object belongs to.

class

   Name of the class the documented object belongs to.  Only available
   for methods and attributes.

underline

   A string containing "len(full_name) * '='". Use the "underline"
   filter instead.

members

   List containing names of all members of the module or class.  Only
   available for modules and classes.

inherited_members

   List containing names of all inherited members of class.  Only
   available for classes.

   New in version 1.8.0.

functions

   List containing names of "public" functions in the module.  Here,
   "public" means that the name does not start with an underscore.
   Only available for modules.

classes

   List containing names of "public" classes in the module.  Only
   available for modules.

exceptions

   List containing names of "public" exceptions in the module.  Only
   available for modules.

methods

   List containing names of "public" methods in the class.  Only
   available for classes.

attributes

   List containing names of "public" attributes in the class/module.
   Only available for classes and modules.

   Changed in version 3.1: Attributes of modules are supported.

modules

   List containing names of "public" modules in the package.  Only
   available for modules that are packages and the "recursive" option
   is on.

   New in version 3.1.

Additionally, the following filters are available

escape(s)

   Escape any special characters in the text to be used in formatting
   RST contexts. For instance, this prevents asterisks making things
   bold. This replaces the builtin Jinja escape filter that does html-
   escaping.

underline(s, line='=')

   Add a title underline to a piece of text.

For instance, "{{ fullname | escape | underline }}" should be used to
produce the title of a page.

Note:

  You can use the "autosummary" directive in the stub pages. Stub
  pages are generated also based on these directives.
