`sphinx.ext.autosummary` – Gera resumos autodoc¶

Adicionado na versão 0.6.

Essa extensão gera lista resumida de função/método/atributo, similar a saída produzida pelo Epydoc e outras ferramentas para API. Isso é especialmente útil quando as strings dos docs são longas e detalhadas e separando cada uma em página diferente torna mais fácil a leitura.

A extensão sphinx.ext.autosummary faz isso em duas partes:

Há uma diretiva para gerar listagens resumidas autosummary que contém links para itens documentados e sumário extraído dessas strings de docs.
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::¶

Inserir uma tabela que contém links para os itens documentados e um pequeno sumário (a primeira sentença do docstring) para cada um desses.

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.

Por examplo,

.. currentmodule:: sphinx

.. autosummary::

   environment.BuildEnvironment
   util.relative_uri

produz uma tabela como esta:

`environment.BuildEnvironment`(app)	O ambiente no qual os arquivos ReSt são traduzidos.
`util.relative_uri`(base, to)	Retorna URL relativa da `base` para `destino`.

Autosummary preprocessa as docstrings e assinaturas no mesmo evento autodoc-process-docstring e autodoc-process-signature comporta-se como autodoc.

Opções

Se deseja que a tabela autosummary também sirva como entrada toctree usar opção toctree, por exemplo:
```
.. autosummary::
   :toctree: DIRNAME

   sphinx.environment.BuildEnvironment
   sphinx.util.relative_uri
```
A opção toctree também sinaliza ao script sphinx-autogen que páginas stub devem ter entradas geradas e listadas nessa diretiva. A opção aceita nome de diretório como argumento sphinx-autogen como local padrão da saída. Se nenhum argumento é informado, a saída ocorre no mesmo diretório do arquivo da diretiva.

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

Adicionado na versão 3.1: caption option added.

Caso não desejar exibir assinaturas das funções listadas pelo autosummary inclua a opção nosignatures:

.. 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.

Adicionado na versão 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
```
Adicionado na versão 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.

Por exemplo, o comando

$ 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

Gerando páginas stub automaticamente¶

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.

Adicionado na versão 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.

Alterado na versão 2.3: Emits autodoc-skip-member event as autodoc does.

Alterado na versão 4.0: Enabled by default.

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

Adicionado na versão 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.

Adicionado na versão 2.0.

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

Adicionado na versão 2.1.

Alterado na versão 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.

Adicionado na versão 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.

Adicionado na versão 3.2.

Personalizando templates¶

Adicionado na versão 1.0.

You can customize the stub page templates, in a similar way as the HTML Jinja templates, see Criando modelos. (TemplateBridge is not supported.)

Nota

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.

Adicionado na versão 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.

Alterado na versão 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.

Adicionado na versão 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.

Nota

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

Sphinx

On this page

Site navigation

`sphinx.ext.autosummary` – Gera resumos autodoc¶

sphinx-autogen – generate autodoc stub pages¶

Gerando páginas stub automaticamente¶

Personalizando templates¶

Sphinx

sphinx.ext.autosummary – Gera resumos autodoc¶

sphinx-autogen – generate autodoc stub pages¶

Gerando páginas stub automaticamente¶

Personalizando templates¶

`sphinx.ext.autosummary` – Gera resumos autodoc¶