Geração automática de documentação a partir do código

Na seção anterior do tutorial você documentou manualmente uma função Python no Sphinx. No entanto, a descrição estava fora de sincronia com o próprio código, pois a assinatura da função não era a mesma. Além disso, seria bom reutilizar Python docstrings na documentação, ao invés de ter que escrever as informações em dois lugares.

Felizmente, a extensão autodoc fornece essa funcionalidade.

Reutilizando assinaturas e docstrings com autodoc

Para usar o autodoc, primeiro adicione-o à lista de extensões habilitadas:

docs/source/conf.py
extensions = [
    'sphinx.ext.duration',
    'sphinx.ext.doctest',
    'sphinx.ext.autodoc',
]

Em seguida, mova o conteúdo da diretiva .. py:function para a função docstring no arquivo Python original, como segue:

lumache.py
def get_random_ingredients(kind=None):
    """
    Return a list of random ingredients as strings.

    :param kind: Optional "kind" of ingredients.
    :type kind: list[str] or None
    :raise lumache.InvalidKindError: If the kind is invalid.
    :return: The ingredients list.
    :rtype: list[str]

    """
    return ["shells", "gorgonzola", "parsley"]

Finalmente, substitua a diretiva .. py:function da documentação do Sphinx por autofunction:

docs/source/usage.rst
you can use the ``lumache.get_random_ingredients()`` function:

.. autofunction:: lumache.get_random_ingredients

Se você agora construir a documentação HTML, a saída será a mesma! Com a vantagem de ser gerado a partir do próprio código. Sphinx pegou o reStructuredText da docstring e o incluiu, também gerando referências cruzadas apropriadas.

Você também pode gerar automaticamente a documentação de outros objetos. Por exemplo, adicione o código para a exceção Invalid KindError:

lumache.py
class InvalidKindError(Exception):
    """Raised if the kind is invalid."""
    pass

E substitua a diretiva .. py:exception por autoexception da seguinte forma:

docs/source/usage.rst
or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
will raise an exception.

.. autoexception:: lumache.InvalidKindError

E novamente, depois de executar make html, a saída será a mesma de antes.

Gerando referências de API abrangentes

Enquanto usar sphinx.ext.autodoc torna muito mais fácil manter o código e a documentação em sincronia, ainda requer que você escreva uma diretiva auto* para cada objeto que você deseja documentar. Sphinx fornece ainda outro nível de automação: a extensão autosummary.

A diretiva autosummary gera documentos que contêm todas as diretivas autodoc necessárias. Para usá-la, primeiro habilite a extensão autosummary:

docs/source/conf.py
extensions = [
   'sphinx.ext.duration',
   'sphinx.ext.doctest',
   'sphinx.ext.autodoc',
   'sphinx.ext.autosummary',
]

Em seguida, crie um novo arquivo api.rst com este conteúdo:

docs/source/api.rst
API
===

.. autosummary::
   :toctree: generated

   lumache

Lembre-se de incluir o novo documento na toctree raiz:

docs/source/index.rst
Contents
--------

.. toctree::

   usage
   api

Finalmente, depois de construir a documentação HTML executando make html, ela conterá duas novas páginas:

  • api.html, correspondente a docs/source/api.rst e contendo uma tabela com os objetos que você incluiu na diretiva autosummary (neste caso, apenas um).

  • generated/lumache.html, correspondendo a um arquivo reStructuredText recém-criado generated/lumache.rst e contendo um resumo dos membros do módulo, neste caso uma função e uma exceção.

Página de resumo criada por autosummary

Página de resumo criada por autosummary

Cada um dos links na página de resumo irá levá-lo aos lugares onde você originalmente usou a diretiva autodoc correspondente, neste caso no documento usage.rst.

Nota

Os arquivos gerados são baseados em modelos Jinja2 que podem ser personalizados, mas isso está fora do escopo deste tutorial.