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

Essa extensão pode importar módulos que estão sendo documentados, e carregar na documentação a partir de docstrings de forma semiautomática.

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 os módulos a serem documentados. 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 principais estejam protegidas por uma condição if __name__ == '__main__'.

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 ela acabará 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 do Google ao do reStructuredText, você também pode habilitar a extensão napoleon. napoleon é um pré-processador que converte suas 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

vai produzir fonte assim:

.. class:: Noodle

   Noodle's docstring.

As diretivas “auto” também podem conter conteúdo próprio, elas serão inseridas na fonte 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)

Se definido, autodoc vai gerar documento para os membros do exceção, classe ou módulo alvo.

Por exemplo:

.. automodule:: noodle
   :members:

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

.. autoclass:: Noodle
   :members:

vai documentar todos os métodos e propriedades de membro da classe.

Por padrão, autodoc não vai gerar documento para os membros que são privados, não tendo docstrings, herdados a partir de uma superclasse ou membros especiais.

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)

Se definido, autodoc também gerará documento para os membros que não possuem docstrings:

.. automodule:: noodle
   :members:
   :undoc-members:
:private-members: (no value or comma separated list)

Se definido, autodoc também irá gerar documentos para os membros privados (ou seja, aqueles nomeados como _private ou __private):

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

Também pode levar uma lista explícita de nomes de membros a serem documentados como argumentos:

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

Novo na versão 1.1.

Alterado na versão 3.2: A opção agora pode receber argumentos.

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

Se definido, autodoc também irá gerar documentos para os membros especiais (ou seja, aqueles nomeados como __special__)

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

Também pode levar uma lista explícita de nomes de membros a serem documentados como argumentos:

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

Novo na versão 1.1.

Alterado na versão 1.2: Esta opção agora aceita argumentos

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

    Você pode usar as opções de diretiva do autodoc para substituir ou estender temporariamente as opções padrão que usam a lista como uma entrada. Por exemplo:

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

    Alterado na versão 3.5: As opções padrão podem ser substituídas ou estendidas temporariamente.

  • autodoc considera um membro privado se sua docstring contém :meta private: em sua Lista Informação Campos. Por exemplo:

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

    Novo na versão 3.0.

  • autodoc considera um membro público se sua docstring contém :meta public: em sua Lista Informação Campos, mesmo se começar com um sublinhado. Por exemplo:

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

    Novo na versão 3.1.

  • autodoc considera que um membro variável não tem nenhum valor padrão se sua docstring contém :meta hide-value: em sua Lista Informação Campos. Exemplo:

    var1 = None  #: :meta hide-value:
    

    Novo na versão 3.5.

  • Para classes e exceções, membros herdados de classes base serão deixados de fora ao documentar todos os membros, a menos que você forneça a opção inherited-members, além de 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.

    Pode ser necessária uma classe ancestral para não documentar membros herdados dela. Por padrão, os membros da classe object não são documentados. Para mostrá-los todos, dê None para a opção.

    Por exemplo: se sua classe Foo é derivada da classe list e você não deseja documentar list.__len__(), você deve especificar uma opção :inherited-members: list para evitar membros especiais da classe de lista.

    Outro exemplo: se sua classe Foo tem um método especial __str__ e a diretiva autodoc tem ambos inherited-members e special-members, __str__ será documentado como no passado, mas outro método especial que não são implementados em sua classe Foo.

    Desde a v5.0, ele pode receber uma lista separada por vírgulas de classes ancestrais. Ele permite suprimir membros herdados de várias classes no módulo de uma vez especificando a opção para a diretiva automodule.

    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: Leva um nome de classe ancestral como argumento.

    Alterado na versão 5.0: É preciso uma lista separada por vírgulas de nomes de classes ancestrais.

  • É possível substituir a assinatura de objetos chamáveis explicitamente (funções, métodos, classes) explicitamente com a sintaxe regular que irá substituir 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 oferecem suporte a um sinalizador opcional chamado 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 oferecem suporte a um sinalizador 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 à qual a diretiva padrão py:module oferece suporte.

    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 oferecem suporte à 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 fonte 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.

  • Como uma dica para a extensão autodoc, você pode colocar um separador :: entre o nome do módulo e o nome do objeto para permitir que o autodoc saiba o nome correto do módulo se for ambíguo.

    .. autoclass:: module.name::Noodle
    
  • autoclass também reconhece a opção class-doc-from que pode ser usada para substituir o valor global de autoclass_content.

    Novo na versão 4.1.

.. autofunction::
.. autodecorator::
.. autodata::
.. automethod::
.. autoattribute::
.. autoproperty::

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

autodata e autoattribute oferecem suporte à opção annotation. A opção controla como o valor da variável é mostrado. Se especificado sem argumentos, apenas o nome da variável será impresso, e seu valor não é mostrado:

.. autodata:: CD_DRIVE
   :annotation:

Se a opção for especificada com argumentos, ela é impressa após o nome como um valor da variável:

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

Por padrão, sem a opção annotation, Sphinx tenta obter o valor da variável e imprimi-lo após o nome.

A opção no-value pode ser usada em vez de uma annotation em branco para mostrar a dica de tipo, mas não o valor:

.. autodata:: CD_DRIVE
   :no-value:

Se as opções annotation e no-value forem usadas, no-value tem nenhum efeito.

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 após a definição. Os comentários precisam estar em uma linha de sua própria definição, ou imediatamente após a atribuição na mesma linha. A última forma é restrita a apenas uma linha.

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

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 2.1: autoproperty adicionado.

Alterado na versão 3.4: autodata e autoattribute agora têm uma opção no-value.

Nota

Se você documentar funções ou métodos decorados, tenha em mente que o autodoc obtém 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"

As docstrings da classe e do método __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

Este valor seleciona como a assinatura será exibida para a classe definida pela diretiva autoclass. Os valores possíveis são:

"mixed"

Exibe a assinatura com o nome da classe.

"separated"

Exibe a assinatura como um método.

O padrão é "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 sinalizadores de diretivas do autodoc que devem ser aplicados automaticamente a todas as diretivas do autodoc. Os sinalizadores suportados 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 do autodoc. Eles são aplicados a todas as diretivas do 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.

As opções válidas são 'members', 'member-order', 'undoc-members', 'private-members', 'special-members', 'inherited-members', 'show-inheritance', 'ignore-module-all', 'imported-members', 'exclude-members', 'class-doc-from' e 'no-value'.

Novo na versão 1.8.

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

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

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

Alterado na versão 4.5: Adicionado 'no-value'.

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 frequentemente 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 do conteúdo da docstring.

autodoc continuará a procurar por várias linhas de assinatura, parando na primeira linha que não se parece com uma assinatura. Isso é útil para declarar assinaturas de função sobrecarregadas.

Novo na versão 1.1.

Alterado na versão 3.1: Suporte a assinaturas sobrecarregadas

Alterado na versão 4.0: Assinaturas sobrecarregadas não precisam ser separadas por uma barra invertida

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"]

Fará um mock de 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 mockados.

autodoc_typehints

Este valor controla como representar dicas de tipo. A configuração presume os seguintes valores:

  • 'signature' – Mostra dicas de tipo na assinatura (padrão)

  • 'description' – Mostra dicas de tipo como conteúdo da função ou método As dicas de tipo de funções ou métodos sobrecarregados ainda serão representadas na assinatura.

  • 'none' – Não mostra dicas de tipo

  • 'both' – Mostra dicas de tipo na assinatura e como conteúdo da função ou método

Funções ou métodos sobrecarregados não terão dicas de tipo incluídas na descrição porque é impossível representar com precisão todas as sobrecargas possíveis como uma lista de parâmetros.

Novo na versão 2.1.

Novo na versão 3.0: A nova opção 'description' foi adicionada.

Novo na versão 4.1: A nova opção 'both' foi adicionada.

autodoc_typehints_description_target

Este valor controla se os tipos de parâmetros não documentados e valores de retorno são documentados quando autodoc_typehints é definido como description.

O valor padrão é "all", o que significa que os tipos são documentados para todos os parâmetros e valores de retorno, sejam eles documentados ou não.

Quando definido como "documented", os tipos só serão documentados para um parâmetro ou valor de retorno que já está documentado pela docstring.

Com "documented_params", os tipos de parâmetro só serão anotados se o parâmetro estiver documentado na docstring. O tipo de retorno é sempre anotado (exceto se for None).

Novo na versão 4.0.

Novo na versão 5.0: Nova opção 'documented_params' foi adicionada.

autodoc_type_aliases

Um dicionário para apelidos de tipo definidos pelos usuários que mapeia um nome de tipo para o nome de objeto totalmente qualificado. É usado para manter os apelidos de tipo não avaliados no documento. O padrão é vazio ({}).

Os aliases de tipo só estão disponíveis se o seu programa habilitar o recurso Avaliação Adiada de Anotações (PEP 563) via from __future__ import annotations.

Por exemplo, aqui está um código usando um apelido de tipo:

from __future__ import annotations

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

def f() -> AliasType:
    ...

Se autodoc_type_aliases não estiver definido, autodoc irá gerar marcação interna a partir deste código da seguinte forma:

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

   ...

Se você definir autodoc_type_aliases como {'AliasType': 'your.module.AliasType'}, ele gera o seguinte documento internamente:

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

   ...

Novo na versão 3.3.

autodoc_typehints_format

Este valor controla o formato das dicas de tipo. A configuração assume os seguintes valores:

  • 'fully-qualified' – Mostra o nome do módulo e seu nome de dicas de tipo

  • 'short' – Suprime os nomes dos módulos principais das dicas de tipo (p. ex., io.StringIO -> StringIO) (padrão)

Novo na versão 4.4.

Alterado na versão 5.0: A configuração padrão foi alterada para 'short'

autodoc_preserve_defaults

Se for True, os valores de argumento padrão das funções não serão avaliados na geração do documento. Ele os preserva como estão no código-fonte.

Novo na versão 4.0: Adicionado como um recurso experimental. Isso será integrado ao autodoc core no futuro.

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

Este valor controla a herança de docstrings. Se definido como True, a docstring para classes ou métodos, se não for definida explicitamente, é herdada dos pais.

O padrão é True.

Novo na versão 1.7.

suppress_warnings

autodoc oferece suporte à supressão de mensagens de aviso através de suppress_warnings. Ele permite seguir os seguintes tipos de avisos:

  • autodoc

  • autodoc.import_object

Pré-processamento de docstrings

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

Emitido antes do autodoc formatar uma assinatura para um objeto. O manipulador de eventos pode modificar um objeto para alterar sua assinatura.

Parâmetros:
  • app – o objeto do aplicativo Sphinx

  • obj – o objeto em si

  • bound_method – um booleano indica que um objeto é um método vinculado ou não

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 totalmente qualificado 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 – anotação do retorno da função 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: str = None) Callable[código fonte]

Retorna um “listener” que remove o primeiro pre e as últimas linhas post de cada docstring. Se what for uma sequê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: Sequence[str] = None, keepempty: bool = False, exclude: bool = False) Callable[código fonte]

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 sequência de strings, somente as docstrings de um tipo em what serão processadas.

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

Emitido quando autodoc leu e processou uma classe para determinar as classes básicas. bases é uma lista de classes que o manipulador de eventos pode modificar no local para alterar o que o Sphinx coloca na saída. É emitido apenas se a opção show-inheritance for fornecida.

Parâmetros:
  • app – o objeto do aplicativo Sphinx

  • name – o nome totalmente qualificado do objeto

  • obj – o objeto em si

  • options – as opções fornecidas para a diretiva da classe

  • bases – a lista de assinatura de classes base, veja acima.

Novo na versão 4.1.

Alterado na versão 4.3: bases pode conter uma string como nome de classe base. Ele será processado como texto com marcação reST.

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 totalmente qualificado do objeto

  • obj – o objeto em si

  • skip – um booleano indicando se o autodoc pulará este membro se o manipulador de usuário não substituir 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