sphinx.ext.autodoc - Inclui documentação das docstrings

Essa extensão pode importar modulos que estão sendo documentados, e carregar na documentação a partir de docstrings com certo automatismo.

Nota

Para o Sphinx (na verdade, o interpretador Python que executa o Sphinx) para localizar seu módulo, ele deve ser importável. Isso significa que o módulo ou o pacote deve estar em um dos diretórios em sys.path - adapte seu sys.path no arquivo de configuração de acordo.

Aviso

autodoc importa módulos para documentar. Se algum módulo tiver efeitos na importação, serão executados por autodoc quando sphinx-build for executado.

Se os scripts do seu documento, (diferentemente de módulos de biblioteca), certificar-se que suas rotinas main estejam protegidas por um if __name__ == '__main__' condição.

Para que isso funcione, as docstrings devem, é claro, ser escritas em reStructuredText correto. Você pode então usar toda a marcação usual do Sphinx nas docstrings, e terminará corretamente na documentação. Juntamente com a documentação escrita à mão, essa técnica facilita a manutenção de dois locais para a documentação, evitando, ao mesmo tempo, a documentação pura da API com aparência gerada automaticamente.

Se você prefere o estilo das docstrings do NumPy ou Google sobre reStructuredText, você também pode habilitar a extensão napoleon. napoleon é um pré-processador que converte seus docstrings para corrigir o reStructuredText antes que o autodoc os processe.

Diretivas

autodoc fornece várias diretivas que são versões do usual py:module, py:class e assim por diante. No tempo de análise, eles importam o módulo correspondente e extraem a docstring dos objetos fornecidos, inserindo-os na fonte da página sob uma diretiva apropriada py:module, py:class etc.

Nota

Assim como py:class respeita a corrente py:module, autoclass também o fará. Da mesma forma, automethod respeitará a atual py:class.

.. automodule::

.. autoclass::

.. autoexception::

Documente um módulo, classe ou exceção. Todas as três diretivas, por padrão, apenas inserem a docstring do próprio objeto:

.. autoclass:: Noodle

irá produzir fonte assim:

.. class:: Noodle

   Noodle's docstring.

As diretivas auto também podem conter conteúdo próprio, elas serão inseridas na origem da diretiva não automática resultante após a docstring (mas antes de qualquer documentação de membro automática).

Portanto, você também pode misturar documentação de membros automático e não automático, como:

.. autoclass:: Noodle
   :members: eat, slurp

   .. method:: boil(time=10)

      Boil the noodle *time* minutes.

Opções

:members: (no value or comma separated list)

If set, autodoc will generate document for the members of the target module, class or exception.

Por exemplo:

.. automodule:: noodle
   :members:

documentará todos os membros do módulo (recursivamente) e:

.. autoclass:: Noodle
   :members:

will document all class member methods and properties.

By default, autodoc will not generate document for the members that are private, not having docstrings, inherited from super class, or special members.

Para módulos, __all__ será respeitado ao procurar por membros, a menos que você forneça a opção de sinalizador ignore-module-all. Sem ignore-module-all, a ordem dos membros também será a ordem em __all__.

Você também pode fornecer uma lista explícita de membros; somente estes serão então documentados:

.. autoclass:: Noodle
   :members: eat, slurp

:undoc-members: (no value)

If set, autodoc will also generate document for the members not having docstrings:

.. automodule:: noodle
   :members:
   :undoc-members:

:private-members: (no value or comma separated list)

If set, autodoc will also generate document for the private members (that is, those named like _private or __private):

.. automodule:: noodle
   :members:
   :private-members:

It can also take an explicit list of member names to be documented as arguments:

.. automodule:: noodle
   :members:
   :private-members: _spicy, _garlickly

Novo na versão 1.1.

Alterado na versão 3.2: The option can now take arguments.

:special-members: (no value or comma separated list)

If set, autodoc will also generate document for the special members (that is, those named like __special__):

.. autoclass:: my.Class
   :members:
   :special-members:

It can also take an explicit list of member names to be documented as arguments:

.. autoclass:: my.Class
   :members:
   :special-members: __init__, __name__

Novo na versão 1.1.

Alterado na versão 1.2: The option can now take arguments

Opções e uso avançado

• Se você deseja tornar a opção members (ou outras opções descritas abaixo) como padrão, consulte autodoc_default_options.

  Dica

  Você pode usar um formato negado, 'no-flag', como uma opção da diretiva autodoc, para desativá-lo temporariamente. Por exemplo:

  .. automodule:: foo
     :no-undoc-members:
  

  Dica

  You can use autodoc directive options to temporarily override or extend default options which takes list as an input. For example:

  .. autoclass:: Noodle
     :members: eat
     :private-members: +_spicy, _garlickly
  

  Alterado na versão 3.5: The default options can be overridden or extended temporarily.

• autodoc considers a member private if its docstring contains :meta private: in its Lista Informação Campos. For example:

  def my_function(my_arg, my_other_arg):
      """blah blah blah
  
      :meta private:
      """
  

  Novo na versão 3.0.

• autodoc considers a member public if its docstring contains :meta public: in its Lista Informação Campos, even if it starts with an underscore. For example:

  def _my_function(my_arg, my_other_arg):
      """blah blah blah
  
      :meta public:
      """
  

  Novo na versão 3.1.

• autodoc considers a variable member does not have any default value if its docstring contains :meta hide-value: in its Lista Informação Campos. Example:

  var1 = None  #: :meta hide-value:
  

  Novo na versão 3.5.

• For classes and exceptions, members inherited from base classes will be left out when documenting all members, unless you give the inherited-members option, in addition to members:

  .. autoclass:: Noodle
     :members:
     :inherited-members:
  

  Isso pode ser combinado com undoc-members para documentar todos os membros disponíveis da classe ou módulo.

  It can take an ancestor class not to document inherited members from it. By default, members of object class are not documented. To show them all, give None to the option.

  For example; If your class Foo is derived from list class and you don’t want to document list.__len__(), you should specify a option :inherited-members: list to avoid special members of list class.

  Another example; If your class Foo has __str__ special method and autodoc directive has both inherited-members and special-members, __str__ will be documented as in the past, but other special method that are not implemented in your class Foo.

  Nota: isso levará a erros de marcação se os membros herdados vierem de um módulo cujas docstrings não são formatadas em reST.

  Novo na versão 0.3.

  Alterado na versão 3.0: It takes an ancestor class name as an argument.

• É possível sobrescrever a assinatura de objetos que podem ser chamados explicitamente (funções, métodos, classes) explicitamente com a sintaxe regular que irá sobrepor a assinatura obtida da introspecção:

  .. autoclass:: Noodle(type)
  
     .. automethod:: eat(persona)
  

  Isso é útil se a assinatura do método estiver oculta por um decorador.

  Novo na versão 0.4.

• As diretivas automodule, autoclass e autoexception também suportam uma flag opcional chamada show-inheritance. Quando fornecida, uma lista de classes base será inserida logo abaixo da assinatura da classe (quando usada com automodule, ela será inserida para cada classe documentada no módulo).

  Novo na versão 0.4.

• Todas as diretivas autodoc suportam a flag opcional noindex que tem o mesmo efeito que as diretivas padrão py:function etc.: nenhuma entrada de índice é gerada para o objeto documentado (e todos os membros autodocumentados).

  Novo na versão 0.4.

• automodule também reconhece as opções synopsis, platform e deprecated que a diretiva padrão py:module suporta.

  Novo na versão 0.5.

• automodule e autoclass também tem uma opção member-order que pode ser usada para substituir o valor global de autodoc_member_order para uma diretiva.

  Novo na versão 0.6.

• As diretivas que suportam a documentação do membro também têm uma opção exclude-members que pode ser usada para excluir nomes de membros únicos da documentação, se todos os membros tiverem que ser documentados.

  Novo na versão 0.6.

• Em uma diretiva automodule com o conjunto de opções members, apenas membros do módulo cujo atributo __module__ é igual ao nome do módulo fornecido a automodule serão documentados. Isso evita a documentação de classes ou funções importadas. Defina a opção imported-members se você quiser evitar esse comportamento e documentar todos os membros disponíveis. Observe que os atributos dos módulos importados não serão documentados, porque a documentação de atributos é descoberta ao analisar o arquivo de origem do módulo atual.

  Novo na versão 1.2.

• Adiciona uma lista de módulos no autodoc_mock_imports para evitar que os erros de importação interrompam o processo de construção quando algumas dependências externas não puderem ser importadas no momento da criação.

  Novo na versão 1.3.

• As a hint to autodoc extension, you can put a :: separator in between module name and object name to let autodoc know the correct module name if it is ambiguous.

  .. autoclass:: module.name::Noodle
  

• autoclass also recognizes the class-doc-from option that can be used to override the global value of autoclass_content.

  Novo na versão 4.1.

.. autofunction::

.. autodecorator::

.. autodata::

.. automethod::

.. autoattribute::

Estes funcionam exatamente como autoclass etc., mas não oferecem as opções usadas para documentação automática de membros.

autodata and autoattribute support the annotation option. The option controls how the value of variable is shown. If specified without arguments, only the name of the variable will be printed, and its value is not shown:

.. autodata:: CD_DRIVE
   :annotation:

If the option specified with arguments, it is printed after the name as a value of the variable:

.. autodata:: CD_DRIVE
   :annotation: = your CD device name

By default, without annotation option, Sphinx tries to obtain the value of the variable and print it after the name.

The no-value option can be used instead of a blank annotation to show the type hint but not the value:

.. autodata:: CD_DRIVE
   :no-value:

If both the annotation and no-value options are used, no-value has no effect.

Para membros de dados do módulo e atributos de classe, a documentação pode ser colocada em um comentário com formatação especial (usando #: para iniciar o comentário em vez de apenas #) ou em uma docstring depois a definição. Os comentários precisam estar em uma linha de sua própria definição, ou imediatamente após a atribuição on the same line. A última forma é restrita a apenas uma linha.

Isso significa que, na definição de classe a seguir, todos os atributos podem ser autodocumented:

class Foo:
    """Docstring for class Foo."""

    #: Doc comment for class attribute Foo.bar.
    #: It can have multiple lines.
    bar = 1

    flox = 1.5   #: Doc comment for Foo.flox. One line only.

    baz = 2
    """Docstring for class attribute Foo.baz."""

    def __init__(self):
        #: Doc comment for instance attribute qux.
        self.qux = 3

        self.spam = 4
        """Docstring for instance attribute spam."""

Alterado na versão 0.6: autodata e autoattribute agora podem extrair docstrings.

Alterado na versão 1.1: Os documentos de comentários agora são permitidos na mesma linha após uma atribuição.

Alterado na versão 1.2: autodata e autoattribute possuem uma opção annotation.

Alterado na versão 2.0: autodecorator adicionado.

Alterado na versão 3.4: autodata and autoattribute now have a no-value option.

Nota

Se você documentar funções ou métodos decorados, tenha em mente que o autodoc recupera suas docstrings importando o módulo e inspecionando o atributo __doc__ da função ou método dado. Isso significa que se um decorador substituir a função decorada por outra, deverá copiar o __doc__ original para a nova função.

Configuração

Existem também valores de configuração que você pode definir:

autoclass_content

Este valor seleciona qual conteúdo será inserido no corpo principal de uma diretiva autoclass. Os valores possíveis são:

"class"

Apenas a docstring da classe é inserida. Este é o padrão. Você ainda pode documentar __init__ como um método separado usando automethod ou a opção members para autoclass.

"both"

A docstring do método a e __init__ são concatenadas e inseridas.

"init"

Somente a docstring do método __init__ é inserida.

Novo na versão 0.3.

Se a classe não tiver o método __init__ ou se a docstring do método __init__ estiver vazia, mas a classe tem a docstring do método __new__, ela é usada no lugar.

Novo na versão 1.4.

autodoc_class_signature

This value selects how the signautre will be displayed for the class defined by autoclass directive. The possible values are:

"mixed"

Display the signature with the class name.

"separated"

Display the signature as a method.

The default is "mixed".

Novo na versão 4.1.

autodoc_member_order

Esse valor seleciona se os membros documentados automaticamente são classificados em ordem alfabética (valor 'alphabetical'), por tipo de membro (valor 'groupwise') ou por ordem de origem (valor 'bysource'). O padrão é alfabético.

Observe que, para a ordem de origem, o módulo deve ser um módulo Python com o código-fonte disponível.

Novo na versão 0.6.

Alterado na versão 1.0: Suporte para 'bysource'.

autodoc_default_flags

Esse valor é uma lista de flags de diretivas autodoc que devem ser aplicadas automaticamente a todas as diretivas autodoc. As flags suportadas são 'members', 'undoc-members', 'private-members', 'special-members', 'inherited-members', 'show-inheritance', 'ignore-module-all' e 'exclude-members'.

Novo na versão 1.0.

Obsoleto desde a versão 1.8: Integrado em autodoc_default_options.

autodoc_default_options

As opções padrão para diretivas autodoc. Eles são aplicados a todas as diretivas autodoc automaticamente. Deve ser um dicionário que mapeie os nomes das opções para os valores. Por exemplo:

autodoc_default_options = {
    'members': 'var1, var2',
    'member-order': 'bysource',
    'special-members': '__init__',
    'undoc-members': True,
    'exclude-members': '__weakref__'
}

Definir None ou True como o valor é equivalente a fornecer apenas o nome da opção às diretivas.

The supported options are 'members', 'member-order', 'undoc-members', 'private-members', 'special-members', 'inherited-members', 'show-inheritance', 'ignore-module-all', 'imported-members', 'exclude-members' and 'class-doc-from'.

Novo na versão 1.8.

Alterado na versão 2.0: Aceita True como um valor.

Alterado na versão 2.1: Adicionado 'imported-members'.

Alterado na versão 4.1: Added 'class-doc-from'.

autodoc_docstring_signature

As funções importadas dos módulos C não podem ser introspectivas e, portanto, a assinatura dessas funções não pode ser determinada automaticamente. No entanto, é uma convenção freqüentemente usada para colocar a assinatura na primeira linha da docstring da função.

Se este valor booleano é definido como True (que é o padrão), o autodoc irá olhar para a primeira linha da docstring para funções e métodos, e se parecer com uma assinatura, use a linha como assinatura e remova-a da docstring conteúdo.

autodoc will continue to look for multiple signature lines, stopping at the first line that does not look like a signature. This is useful for declaring overloaded function signatures.

Novo na versão 1.1.

Alterado na versão 3.1: Support overloaded signatures

Alterado na versão 4.0: Overloaded signatures do not need to be separated by a backslash

autodoc_mock_imports

Este valor contém uma lista de módulos a serem reproduzidos. Isso é útil quando algumas dependências externas não são atendidas no momento da criação e interrompem o processo de construção. Você só pode especificar o pacote raiz das próprias dependências e omitir os submódulos:

autodoc_mock_imports = ["django"]

Irá “mockar” todas as importações sob o pacote django.

Novo na versão 1.3.

Alterado na versão 1.6: Esse valor de configuração requer apenas para declarar os módulos de nível superior que devem ser ridicularizados.

autodoc_typehints

This value controls how to represent typehints. The setting takes the following values:

• 'signature' – Show typehints in the signature (default)

• 'description' – Show typehints as content of the function or method The typehints of overloaded functions or methods will still be represented in the signature.

• 'none' – Do not show typehints

• 'both' – Show typehints in the signature and as content of the function or method

Overloaded functions or methods will not have typehints included in the description because it is impossible to accurately represent all possible overloads as a list of parameters.

Novo na versão 2.1.

Novo na versão 3.0: New option 'description' is added.

Novo na versão 4.1: New option 'both' is added.

autodoc_typehints_description_target

This value controls whether the types of undocumented parameters and return values are documented when autodoc_typehints is set to description.

The default value is "all", meaning that types are documented for all parameters and return values, whether they are documented or not.

When set to "documented", types will only be documented for a parameter or a return value that is already documented by the docstring.

Novo na versão 4.0.

autodoc_type_aliases

A dictionary for users defined type aliases that maps a type name to the full-qualified object name. It is used to keep type aliases not evaluated in the document. Defaults to empty ({}).

The type aliases are only available if your program enables Postponed Evaluation of Annotations (PEP 563) feature via from __future__ import annotations.

For example, there is code using a type alias:

from __future__ import annotations

AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]

def f() -> AliasType:
    ...

If autodoc_type_aliases is not set, autodoc will generate internal mark-up from this code as following:

.. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]

   ...

If you set autodoc_type_aliases as {'AliasType': 'your.module.AliasType'}, it generates the following document internally:

.. py:function:: f() -> your.module.AliasType:

   ...

Novo na versão 3.3.

autodoc_preserve_defaults

If True, the default argument values of functions will be not evaluated on generating document. It preserves them as is in the source code.

Novo na versão 4.0: Added as an experimental feature. This will be integrated into autodoc core in the future.

autodoc_warningiserror

Esse valor controla o comportamento de sphinx-build -W durante a importação de módulos. Se False for fornecido, autodoc forçadamente suprime o erro se o módulo importado emitir avisos. Por padrão, True.

autodoc_inherit_docstrings

This value controls the docstrings inheritance. If set to True the docstring for classes or methods, if not explicitly set, is inherited from parents.

O padrão é True.

Novo na versão 1.7.

suppress_warnings

autodoc suporta a supressão de mensagens de aviso através do suppress_warnings. Ele permite seguir os seguintes tipos de avisos:

• autodoc

• autodoc.import_object

Pré-processamento de doctring

autodoc fornece os seguintes eventos adicionais:

autodoc-process-docstring(app, what, name, obj, options, lines)

Novo na versão 0.4.

Emitido quando o autodoc leu e processou uma docstring. lines é uma lista de strings – as linhas da docstring processada - que o manipulador de eventos pode modificar in place para alterar o que o Sphinx coloca na saída.

Parâmetros

• app – o objeto do aplicativo Sphinx

• what – o tipo do objeto ao qual a docstring pertence (um dos "module", "class", "exception", "function", "method", "attribute")

• name – o nome completo do objeto

• obj – o objeto em si

• options – as opções dadas à diretiva: um objeto com os atributos inherited_members, undoc_members, show_inheritance e noindex que são verdadeiros se a opção de bandeira com o mesmo nome foi dada à diretiva auto

• lines – as linhas da docstring, veja acima

autodoc-before-process-signature(app, obj, bound_method)

Novo na versão 2.4.

Emitted before autodoc formats a signature for an object. The event handler can modify an object to change its signature.

Parâmetros

• app – o objeto do aplicativo Sphinx

• obj – o objeto em si

• bound_method – a boolean indicates an object is bound method or not

autodoc-process-signature(app, what, name, obj, options, signature, return_annotation)

Novo na versão 0.5.

Emitido quando o autodoc formatou uma assinatura para um objeto. O manipulador de eventos pode retornar uma nova tupla (signature, return_annotation) para alterar o que o Sphinx coloca na saída.

Parâmetros

• app – o objeto do aplicativo Sphinx

• what – o tipo do objeto ao qual a docstring pertence (um dos "module", "class", "exception", "function", "method", "attribute")

• name – o nome completo do objeto

• obj – o objeto em si

• options – as opções dadas à diretiva: um objeto com os atributos inherited_members, undoc_members, show_inheritance e noindex que são verdadeiros se a opção de bandeira com o mesmo nome foi dada à diretiva auto

• signature – assinatura de função, como uma string no formato "(parameter_1, parameter_2)" ou None se a introspecção não tiver sido bem-sucedida e a assinatura não tiver sido especificada na diretiva.

• return_annotation – função return annotation como uma string no formato "-> annotation", ou None se não houver anotação de retorno

O módulo sphinx.ext.autodoc fornece funções de fábrica para o processamento docstring comumente necessário no evento autodoc-process-docstring:

sphinx.ext.autodoc.cut_lines(pre: int, post: int = 0, what: Optional[str] = None) → Callable

Retorna um listner que remove o primeiro pre e as últimas linhas post de cada docstring. Se what for uma seqüência de strings, somente as docstrings de um tipo em what serão processadas.

Use assim (por exemplo, na função setup() do conf.py):

from sphinx.ext.autodoc import cut_lines
app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))

Isso pode (e deve) ser usado no lugar de automodule_skip_lines.

sphinx.ext.autodoc.between(marker: str, what: Optional[Sequence[str]] = None, keepempty: bool = False, exclude: bool = False) → Callable

Retorna um listener que mantém, ou se exclude for True, linhas entre as linhas que correspondem à expressão regular marker. Se nenhuma linha corresponder, a docstring resultante estará vazia, portanto nenhuma alteração será feita a menos que keepempty seja True.

Se what for uma seqüência de strings, somente as docstrings de um tipo em what serão processadas.

autodoc-process-bases(app, name, obj, options, bases)

Novo na versão 4.1.

Emitted when autodoc has read and processed a class to determine the base-classes. bases is a list of classes that the event handler can modify in place to change what Sphinx puts into the output. It’s emitted only if show-inheritance option given.

Parâmetros

• app – o objeto do aplicativo Sphinx

• name – o nome completo do objeto

• obj – o objeto em si

• options – the options given to the class directive

• bases – the list of base classes signature. see above.

Ignorando membros

O autodoc permite que o usuário defina um método personalizado para determinar se um membro deve ser incluído na documentação usando o seguinte evento:

autodoc-skip-member(app, what, name, obj, skip, options)

Novo na versão 0.5.

Emitido quando o autodoc tem que decidir se um membro deve ser incluído na documentação. O membro é excluído se um manipulador retornar True. Está incluído se o manipulador retornar False.

Se mais de uma extensão ativada manipular o evento autodoc-skip-member, o autodoc usará o primeiro valor não-None retornado por um manipulador. Os manipuladores devem retornar None para retornar ao comportamento de salto do autodoc e de outras extensões ativadas.

Parâmetros

• app – o objeto do aplicativo Sphinx

• what – o tipo do objeto ao qual a docstring pertence (um dos "module", "class", "exception", "function", "method", "attribute")

• name – o nome completo do objeto

• obj – o objeto em si

• skip – um booleano indicando se autodoc pulará este membro se o manipulador de usuário não anular a decisão

• options – as opções dadas à diretiva: um objeto com os atributos inherited_members, undoc_members, show_inheritance e noindex que são verdadeiros se a opção de bandeira com o mesmo nome foi dada à diretiva auto