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 sinalizadorignore-module-all
. Semignore-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
Adicionado 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__
Adicionado 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, consulteautodoc_default_options
.Dica
Você pode usar um formato negado,
'no-flag'
, como uma opção da diretivaautodoc
, 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: """
Adicionado 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: """
Adicionado 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:
Adicionado 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 demembers
.. 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 classelist
e você não deseja documentarlist.__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 ambosinherited-members
especial-members
,__str__
será documentado como no passado, mas outro método especial que não são implementados em sua classeFoo
.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.
Adicionado 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.
Adicionado na versão 0.4.
As diretivas
automodule
,autoclass
eautoexception
também oferecem suporte a um sinalizador opcional chamadoshow-inheritance
. Quando fornecida, uma lista de classes base será inserida logo abaixo da assinatura da classe (quando usada comautomodule
, ela será inserida para cada classe documentada no módulo).Adicionado na versão 0.4.
All autodoc directives support the
no-index
flag option that has the same effect as for standardpy:function
etc. directives: no index entries are generated for the documented object (and all autodocumented members).Adicionado na versão 0.4.
automodule
também reconhece as opçõessynopsis
,platform
edeprecated
à qual a diretiva padrãopy:module
oferece suporte.Adicionado na versão 0.5.
automodule
eautoclass
também tem uma opçãomember-order
que pode ser usada para substituir o valor global deautodoc_member_order
para uma diretiva.Adicionado 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.Adicionado na versão 0.6.
Em uma diretiva
automodule
com o conjunto de opçõesmembers
, apenas membros do módulo cujo atributo__module__
é igual ao nome do módulo fornecido aautomodule
serão documentados. Isso evita a documentação de classes ou funções importadas. Defina a opçãoimported-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.Adicionado 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.Adicionado 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çãoclass-doc-from
que pode ser usada para substituir o valor global deautoclass_content
.Adicionado 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
eautoattribute
oferecem suporte à opçãoannotation
. 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 umaannotation
em branco para mostrar a dica de tipo, mas não o valor:.. autodata:: CD_DRIVE :no-value:
Se as opções
annotation
eno-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
eautoattribute
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
eautoattribute
possuem uma opçãoannotation
.Alterado na versão 2.0:
autodecorator
adicionado.Alterado na versão 2.1:
autoproperty
adicionado.Alterado na versão 3.4:
autodata
eautoattribute
agora têm uma opçãono-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 usandoautomethod
ou a opçãomembers
paraautoclass
."both"
As docstrings da classe e do método
__init__
são concatenadas e inseridas."init"
Somente a docstring do método
__init__
é inserida.
Adicionado 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.Adicionado 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"
.Adicionado 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.
Adicionado 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'
.Adicionado 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
ouTrue
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'
.Adicionado 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.
Adicionado 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
.Adicionado 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.
Adicionado na versão 2.1.
Adicionado na versão 3.0: A nova opção
'description'
foi adicionada.Adicionado 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 comodescription
.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 forNone
).Adicionado na versão 4.0.
Adicionado 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: ...
Adicionado 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)
Adicionado 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.
Adicionado 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. SeFalse
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
.Adicionado na versão 1.7.
- suppress_warnings
autodoc
oferece suporte à supressão de mensagens de aviso através desuppress_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)¶
Adicionado 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 – the options given to the directive: an object with attributes
inherited_members
,undoc_members
,show_inheritance
andno-index
that are true if the flag option of same name was given to the auto directivelines – as linhas da docstring, veja acima
- autodoc-before-process-signature(app, obj, bound_method)¶
Adicionado 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)¶
Adicionado 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 – the options given to the directive: an object with attributes
inherited_members
,undoc_members
,show_inheritance
andno-index
that are true if the flag option of same name was given to the auto directivesignature – assinatura de função, como uma string no formato
"(parameter_1, parameter_2)"
ouNone
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"
, ouNone
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 = 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()
doconf.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 = 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.
Adicionado 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)¶
Adicionado 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 retornarFalse
.Se mais de uma extensão ativada manipular o evento
autodoc-skip-member
, o autodoc usará o primeiro valor nãoNone
retornado por um manipulador. Os manipuladores devem retornarNone
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 – the options given to the directive: an object with attributes
inherited_members
,undoc_members
,show_inheritance
andno-index
that are true if the flag option of same name was given to the auto directive