`sphinx.ext.napoleon` – Suporte para doctrings de estilo NumPy e Google¶

Autor do módulo: Rob Ruana

Adicionado na versão 1.3.

Visão geral¶

Você está cansado de escrever docstrings que se parecem com isso:

:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:type field_storage: FileStorage
:param temporary: Whether or not to delete the file when the File
   instance is destructed
:type temporary: bool
:returns: A buffered writable file descriptor
:rtype: BufferedFileStorage

reStructuredText é ótimo, mas cria visualmente denso, difícil de ler docstrings. Compare a confusão acima com a mesma coisa reescrita de acordo com o Google Python Style Guide:

Args:
    path (str): The path of the file to wrap
    field_storage (FileStorage): The :class:`FileStorage` instance to wrap
    temporary (bool): Whether or not to delete the file when the File
       instance is destructed

Returns:
    BufferedFileStorage: A buffered writable file descriptor

Muito mais legível, não?

Napoleon é uma extension que permite que o Sphinx analise as documentações de estilo NumPy e Google – o estilo recomendado por Khan Academy.

Napoleon é um pré-processador que analisa docstrings de estilo NumPy e Google e os converte em reStructuredText antes que o Sphinx tente analisá-los. Isso acontece em uma etapa intermediária enquanto o Sphinx está processando a documentação, portanto, não modifica nenhuma das docstrings em seus arquivos de código-fonte reais.

Primeiros passos¶

After setting up Sphinx to build your docs, enable napoleon in the Sphinx conf.py file:

# conf.py

# Add napoleon to the extensions list
extensions = ['sphinx.ext.napoleon']

Use sphinx-apidoc to build your API documentation:
```
$ sphinx-apidoc -f -o docs/source projectdir
```

Docstrings¶

Napoleon interpreta todas as docstrings que autodoc pode encontrar, incluindo docstrings em: modules, classes, attributes, methods, functions, e variables. Dentro de cada docstring, as seções formatadas especialmente são analisadas e convertidas em reStructuredText.

Toda a formatação padrão do reStructuredText ainda funciona conforme o esperado.

Seções Docstring¶

Todos os cabeçalhos de seção a seguir são suportados:

Args (alias de Parameters)
Arguments (alias de Parameters)
Attention
Attributes
Caution
Danger
Error
Example
Examples
Hint
Important
Keyword Args (alias de Keyword Arguments)
Keyword Arguments
Methods
Note
Notes
Other Parameters
Parameters
Return (alias de Returns)
Returns
Raise (apelido de Raises)
Raises
References
See Also
Tip
Todo
Warning
Warnings (alias de Warning)
Warn (apelido de Warns)
Warns
Yield (alias de Yields)
Yields

Google vs NumPy¶

Napoleon suporta dois estilos de docstrings: Google e NumPy. A principal diferença entre os dois estilos é que o Google usa indentação para separar seções, enquanto o NumPy usa underscores.

Google style:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

NumPy style:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    """
    return True

O estilo NumPy tende a exigir mais espaço vertical, enquanto o estilo do Google tende a usar mais espaço horizontal. O estilo do Google tende a ser mais fácil de ler para docstrings curtas e simples, enquanto o estilo NumPy tende a ser mais fácil de ler para docstrings longas e detalhadas.

A escolha entre estilos é em grande parte estética, mas os dois estilos não devem ser misturados. Escolha um estilo para o seu projeto e seja consistente com ele.

Ver também

Para exemplos completos:

Anotações de Tipos¶

PEP 484 introduziu uma maneira padrão de expressar tipos no código Python. Esta é uma alternativa para expressar tipos diretamente em docstrings. Um benefício de expressar tipos de acordo com PEP 484 é que verificadores de tipos e IDEs podem aproveitá-los para análise de código estático. PEP 484 foi então estendido por PEP 526 que introduziu uma maneira semelhante de anotar variáveis (e atributos).

Estilo do Google com anotações do tipo no Python 3:

def func(arg1: int, arg2: str) -> bool:
    """Summary line.

    Extended description of function.

    Args:
        arg1: Description of arg1
        arg2: Description of arg2

    Returns:
        Description of return value

    """
    return True

class Class:
    """Summary line.

    Extended description of class

    Attributes:
        attr1: Description of attr1
        attr2: Description of attr2
    """

    attr1: int
    attr2: str

Estilo do Google com tipos em docstrings:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

class Class:
    """Summary line.

    Extended description of class

    Attributes:
        attr1 (int): Description of attr1
        attr2 (str): Description of attr2
    """

Nota

Python 2/3 compatible annotations não são atualmente suportados pelo Sphinx e não serão exibidos nos documentos.

Configuração¶

Listed below are all the settings used by napoleon and their default values. These settings can be changed in the Sphinx conf.py file. Make sure that “sphinx.ext.napoleon” is enabled in conf.py:

# conf.py

# Add any Sphinx extension module names here, as strings
extensions = ['sphinx.ext.napoleon']

# Napoleon settings
napoleon_google_docstring = True
napoleon_numpy_docstring = True
napoleon_include_init_with_doc = False
napoleon_include_private_with_doc = False
napoleon_include_special_with_doc = True
napoleon_use_admonition_for_examples = False
napoleon_use_admonition_for_notes = False
napoleon_use_admonition_for_references = False
napoleon_use_ivar = False
napoleon_use_param = True
napoleon_use_rtype = True
napoleon_preprocess_types = False
napoleon_type_aliases = None
napoleon_attr_annotations = True

napoleon_google_docstring¶: True ao analisar docstrings Google style . False para desativar o suporte para as doctrings de estilo do Google. O padrão é False.

napoleon_numpy_docstring¶: True ao analisar docstrings NumPy style . False para desabilitar o suporte para docstrings de estilo NumPy. O padrão é True.

napoleon_include_init_with_doc¶

True lista as docstrings/ ``__init___`` separadamente da classe *docstring. False para retornar ao comportamento padrão do Sphinx, que considera a docstring `` __init___ `` como parte da documentação da classe. O padrão é False.

If True:

def __init__(self):
    """
    This will be included in the docs because it has a docstring
    """

def __init__(self):
    # This will NOT be included in the docs

napoleon_include_private_with_doc¶

True inclui membros privados (como _membername) com docstrings na documentação. False para voltar ao comportamento padrão do Sphinx. O padrão é False.

If True:

def _included(self):
    """
    This will be included in the docs because it has a docstring
    """
    pass

def _skipped(self):
    # This will NOT be included in the docs
    pass

napoleon_include_special_with_doc¶

True inclui membros especiais (como __membername__) com docstrings na documentação. False para voltar ao comportamento padrão do Sphinx. O padrão é True.

If True:

def __str__(self):
    """
    This will be included in the docs because it has a docstring
    """
    return unicode(self).encode('utf-8')

def __unicode__(self):
    # This will NOT be included in the docs
    return unicode(self.__class__.__name__)

napoleon_use_admonition_for_examples¶

True usa a diretiva .. admonition:: para as seções Example e Examples. False para usar a diretiva .. rubric::. Um pode parecer melhor do que o outro, dependendo de qual tema HTML é usado. O padrão é False.

Este fragmento NumPy style será convertido da seguinte forma:

Example
-------
This is just a quick example

If True:

.. admonition:: Example

   This is just a quick example

If False:

.. rubric:: Example

This is just a quick example

napoleon_use_admonition_for_notes¶: True utiliza a diretiva .. admonition:: para as seções Notes. False para usar a diretiva .. rubric::. O padrão é False.

Nota

A seção singular Note sempre será convertida em uma diretiva .. note::.

Ver também

napoleon_use_admonition_for_examples

napoleon_use_admonition_for_references¶: True utiliza a diretiva .. admonition:: para as seções References. False para usar a diretiva .. rubric::. O padrão é False.

Ver também

napoleon_use_admonition_for_examples

napoleon_use_ivar¶

True utiliza a função :ivar: para variáveis de instância. False para usar a diretiva .. attribute::. O padrão é False.

Este fragmento NumPy style será convertido da seguinte forma:

Attributes
----------
attr1 : int
    Description of `attr1`

If True:

:ivar attr1: Description of `attr1`
:vartype attr1: int

If False:

.. attribute:: attr1

   Description of `attr1`

   :type: int

napoleon_use_param¶

True utiliza uma função :param: para cada parâmetro de função. False para usar uma única função :parameters: para todos os parâmetros. O padrão é True.

Este fragmento NumPy style será convertido da seguinte forma:

Parameters
----------
arg1 : str
    Description of `arg1`
arg2 : int, optional
    Description of `arg2`, defaults to 0

If True:

:param arg1: Description of `arg1`
:type arg1: str
:param arg2: Description of `arg2`, defaults to 0
:type arg2: :class:`int`, *optional*

If False:

:parameters: * **arg1** (*str*) --
               Description of `arg1`
             * **arg2** (*int, optional*) --
               Description of `arg2`, defaults to 0

napoleon_use_keyword¶

True para utilizar uma função :keyword: para cada argumento de palavra-chave de função. False para usar uma única função :keyword arguments: para todas as palavras-chave. O padrão é True.

This behaves similarly to napoleon_use_param. Note unlike docutils, :keyword: and :param: will not be treated the same way - there will be a separate “Keyword Arguments” section, rendered in the same fashion as “Parameters” section (type links created if possible)

Ver também

napoleon_use_param

napoleon_use_rtype¶

True para utilizar a função :rtype: para o tipo de retorno. False para gerar o tipo de retorno em linha com a descrição. Defaults to True.

Este fragmento NumPy style será convertido da seguinte forma:

Returns
-------
bool
    True if successful, False otherwise

If True:

:returns: True if successful, False otherwise
:rtype: bool

If False:

:returns: *bool* -- True if successful, False otherwise

napoleon_preprocess_types¶: True para converter as definições de tipo nas docstrings como referências. O padrão é False.

Adicionado na versão 3.2.1.

Alterado na versão 3.5: Pré-processa também as docstrings do estilo do Google.

napoleon_type_aliases¶

Um mapeamento para traduzir nomes de tipo para outros nomes ou referências. Funciona apenas quando napoleon_use_param = True. O padrão é None.

Com:

napoleon_type_aliases = {
    "CustomType": "mypackage.CustomType",
    "dict-like": ":term:`dict-like <mapping>`",
}

Este trecho de estilo NumPy:

Parameters
----------
arg1 : CustomType
    Description of `arg1`
arg2 : dict-like
    Description of `arg2`

se torna:

:param arg1: Description of `arg1`
:type arg1: mypackage.CustomType
:param arg2: Description of `arg2`
:type arg2: :term:`dict-like <mapping>`

Adicionado na versão 3.2.

napoleon_attr_annotations¶: True para permitir o uso de anotações de atributos PEP 526 nas classes. Se um atributo estiver documentado na docstring sem um tipo e tiver uma anotação no corpo da classe, esse tipo será usado.

Adicionado na versão 3.4.

napoleon_custom_sections¶

Adiciona uma lista de seções personalizadas a serem incluídas, expandindo a lista de seções analisadas. O padrão é None.

As entradas podem ser strings ou tuplas, dependendo da intenção:

Para criar uma seção “genérica” personalizada, basta passar uma string.
Para criar um alias para uma seção existente, passe uma tupla contendo o nome do alias e o original, nessa ordem.
Para criar uma seção personalizada que seja exibida como a seção de parâmetros ou de retornos, passe uma tupla contendo o nome da seção personalizada e um valor de string, “params_style” ou “returns_style”.

Se uma entrada for apenas uma string, ela será interpretada como um cabeçalho para uma seção genérica. Se a entrada for um contêiner de tupla/lista/indexado, a primeira entrada será o nome da seção, a segunda será a chave de seção a ser emulada. Se o segundo valor de entrada for “params_style” ou “returns_style”, a seção personalizada será exibida como a seção de parâmetros ou a seção de retornos.

Adicionado na versão 1.8.

Alterado na versão 3.5: Suporte a params_style a returns_style

Sphinx

On this page

Site navigation

`sphinx.ext.napoleon` – Suporte para doctrings de estilo NumPy e Google¶

Visão geral¶

Primeiros passos¶

Docstrings¶

Seções Docstring¶

Google vs NumPy¶

Anotações de Tipos¶

Configuração¶

Sphinx

sphinx.ext.napoleon – Suporte para doctrings de estilo NumPy e Google¶

Visão geral¶

Primeiros passos¶

Docstrings¶

Seções Docstring¶

Google vs NumPy¶

Anotações de Tipos¶

Configuração¶

`sphinx.ext.napoleon` – Suporte para doctrings de estilo NumPy e Google¶