neste artigo, vamos passar pelo básico (muito) de gerar documentação a partir de docstrings no seu código Python. É um pouco de moagem, mas depois que você faz isso uma vez, será fácil repetir o processo em cada novo projeto.

para nossos propósitos, vamos assumir que você (1) acredita no valor de documentar o seu código; (2) deseja gerar docs a partir de seus docstrings e (3), optou por usar Sphinx para realizar o trabalho.

finalmente, assume-se que já configurou um ambiente virtual distinto para a sua aplicação. Para os interessados, gosto muito do Gestor de ambiente pyenv. Ele até tem um instalador prático.

terá de instalar a sphinx via pip. No mínimo, você vai precisar da versão 1.3, mas a menos que você tenha uma boa razão, você deve instalar a versão mais recente.

$ pip install sphinx

Step 2: Configurar o seu projecto com arranque rápido

quando instalar o pacote sphinx, também são configurados vários utilitários da linha de comandos.

um desses, sphinx-quickstart irá gerar rapidamente um ficheiro de configuração Básico e uma estrutura de directórios para a sua documentação.

execute este comando na pasta de base do seu projecto (ou seja, a raiz do Acordo de recompra Git). Vai fazer-lhe uma série de perguntas que irão determinar as suas acções. Você pode geralmente aceitar os valores padrão, mas aqui estão algumas sugestões de quando se desviar do padrão:

Após o programa ter executado, você vai notar que uma nova pasta./docs existe na sua pasta do projeto. In addition, there are three new files in that folder: conf.py, andMakefile.

Passo 3: Ajuste da dose conf.py ficheiro

o valor por omissão conf.py ficheiro gerado pelo utilitário quickstart tem cerca de 170 linhas de comprimento, por isso não vou incluir a coisa toda aqui. Há, no entanto, alguns itens que precisamos atualizar antes de continuar.

diga à Sphinx a localização do seu pacote Python

a primeira coisa que precisamos de fazer é indicar onde o pacote Python que contém o seu código de programa está em relação ao ficheiro conf.py. Se a sua estrutura de directórios for semelhante a esta:

Você precisará indicar o conf.py arquivo que Esfinge deve ir “até” um nível de diretório para localizar o pacote Python.

o local para colocar isso é no final da primeira seção do arquivo de configuração. Pouco antes da configuração do General Configuration, você verá isto:

# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

Se não foi comentado, indicaria que o seu pacote está na mesma pasta que o ficheiro conf.py. Você terá que alterá-lo para este:

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

adicione “Napoleon” à lista de extensões de esfinge para usar

fora da caixa, Sphinx só compreende os documentos escritos no texto reStructuredText tradicional. Se você teve o privilégio de trabalhar com esses documentos, você vai saber que eles são uma dor de escrever e não de todo humano amigável para ler ao olhar para eles diretamente no código fonte.

a extensão Napoleon permite que Sphinx entenda docstrings escritas em dois outros formatos populares: NumPy e Google.

tudo o que temos de fazer é adicionar sphinx.ext.napoleon à lista extensions. Quando terminar, deverá ter esta aparência:

extensions = 

Passo 4: Índice de actualização.rst

neste ponto, poderíamos realmente executar o processo de construção para gerar a nossa documentação. Mas seria muito decepcionante. Eis o que teríamos:

tanto Quanto eu gostaria de Esfinge para ir e encontrar o nosso docstrings para nós e organizá-los bem, sem qualquer configuração adicional, não é tão mágico.

para seguir em frente, teremos de fazer algumas modificações menores ao nosso ficheiro , que se parece actualmente com este:

Vamos começar por livrar-se do comentário no topo, que é apenas ruído:

Agora, enquanto há um número de coisas que poderíamos fazer aqui, vamos nos limitar ao mínimo para manter este post para um razoável duração.você vê que.. toctree:: linha? É isso que a Esfinge chama de directiva. Precisamos adicionar diretivas autodoc ao nosso arquivo para que a Sphinx saiba que objetos de código queremos usar a extensão autodoc.

eu vou em frente e adicionar um indicando a Esfinge que eu quero a documento público, os membros do meu main.py módulo dentro de my_project embalagem:

Passo 5: Escreva o Seu Docstrings

Nós não cobriremos a como escrever docstrings em Numpy ou Google estilo neste post.

no Entanto, aqui está o código de main.py que contém um par de simples NumPy estilo docstrings que será captado pelo nosso autodoc directiva:

Passo 6: Gerem os vossos médicos!agora é hora de colher os frutos do seu trabalho. Certifique-se de que você está no ./docs diretório e execute o seguinte: make html

Se você esteve acompanhando até agora, você deve ver algo como isto:

Enquanto você ver aquele glorioso build succeeded mensagem no final, você está pronto para ir e eis que a sua bela criação.

na linha de comandos, execute open _build/html/index.html (ou apenas abra essa página manualmente no seu navegador) e deverá ver algo como isto:

Próximos Passos

Nós apenas arranhamos a superfície aqui e há uma grande quantidade de verrugas ainda em nossa documentação simples.

no próximo post sobre este tema, vamos aprofundar as diretivas da extensão autodoc e alcançar um maior controle do conteúdo e aparência da nossa documentação.