Tutorial Sphinx – Gerando Documentação Para o Seu Código Python

Dando continuidade ao artigo sobre como documentar código em Python, nós vamos falar hoje sobre como gerar documentação automaticamente no seu código Python neste tutorial Sphinx.

O que é o Sphinx

Primeiramente, é importante que falemos um pouco sobre o que é o Sphinx?

sphinx logo

O Sphinx é uma ferramenta de documentação inteligente, que foi desenvolvida pelo Georg Brandl, que também fez parte do Pocoo Team, que entre os projetos desenvolvidos está o Flask, ClickWerkzeugPygments, entre outros.

O Sphinx foi desenvolvido originalmente para suportar documentação na linguagem Python, porém há diversos projetos nas mais variadas linguagens que fazem uso do poder do Sphinx para suportar a sua documentação.




Você pode conferir alguns projetos que estão no Read the Docs neste post do Eric Holscher, que só para citar um exemplo, tem a documentação do phpMyAdmin.

E claro, como não poderia faltar de exemplo, a própria documentação oficial do Python é gerada através do Sphinx.

python docs sphinx

Tutorial Sphinx – O reStructuredText

Antes de prosseguirmos com o nosso tutorial sphinx, nós precisamos falar um pouco sobre o reStructuredText.

O Sphinx faz uso extensivo do reStructuredText como linguagem de marcação para gerar posteriormente a documentação.




O reStructuredText é um parser e um markup WYSIWYG (What You See Is What You Get) e faz parte do projeto docutils.

Com o foco na simplicidade e facilidade de leitura, ele é a marcação utilizada pelo Sphinx para geramos nossos documentos.

reStructuredText Mini Tutorial

Para continuar com o nosso artigo, vamos primeiramente dar uma olhada na sintaxe básica do reStructuredText, para que possamos formatar os nossos documentos.

Negrito e Itálico

Para formatar o nosso texto em negrito ou itálico, é bem simples:


O texto acima seria formatado assim:




Para usar negrito

Para usar itálico

Listas

Outra etapa bem fácil na documentação utilizando o reStructuredText é a criação e manutenção de listas.


A formatação acima nos daria o resultado:

  • Primeiro
  • Segundo
  • Terceiro

Para trabalhar com lista numerada, basta utilizarmos números:


E como resultado, temos:

  1. Primeiro
  2. Segundo
  3. Terceiro

Títulos e Subtítulos

Como vocês podem notar, trabalhar com o reStructuredText é bem tranquilo. Basta lembrar, ou simplesmente consultar como formatar o seu texto e pronto, ele está formatado.

Para trabalhar com títulos e sub títulos é a mesma coisa! Então vamos lá!


Eu não colocarei o resultado desta parte do artigo, pois irá prejudicar o índice dele, mas é bem intuitivo o resultado, certo?!

Instalando o Sphinx

sphinxdoc logo

Como de costume, vamos utilizar o pip para instalar as nossas dependências.

Para fazer uso do Sphix, basta rodar o comando abaixo:

Iniciando o Projeto

Para começar utilizar o Sphinx em nosso projeto, nós temos a facilidade de utilizar o Sphinx Quickstart.

Para começar, vamos criar uma pasta chamada docs, e rodar o comando abaixo:



Após o final da execução do Quickstart, nós teremos a seguinte estrutura em nossa pasta de documentos:

Gerando a Documentação

Para este tutorial sphinx, eu estou usando o meu projeto que eu estou atuando em minhas horas vagas chamado SEO. Para acompanhar, basta acessá-lo no repositório do github: https://github.com/ceb10n/seo.

Vamos facilitar um pouco este tutorial sphinx utilizando o sphinx-apidoc.

Porém, antes nós precisaremos descomentar três linhas de código no arquivo gerado em  docs/source/conf.py:


E agora nós estamos prontos para utilizar o sphinx-apidoc:


Primeiramente, antes de continuarmos este tutorial sphix, eu acho melhor nós esclarecermos um pouco as coisas aqui. Vamos ver um pouco mais sobre o sphinx-apidoc

O que é o sphinx-apidoc

O sphinx-apidoc é uma ferramenta do Sphinx para gerar automaticamente o sources.

Basicamente, ele serve para facilitar a nossa vida!

Para utilizá-lo, o padrão normal de utilização é:


O argumento -o  é utilizado para informar o diretório de saída.

O -f  é utilizado por conveniência para que ele sobrescreva os arquivos caso eles já tenham sido gerados previamente.

Para conferir mais detalhes do sphinx-apidoc, basta acessar a documentação oficial no site do sphinx.

Gerando a documentação em HTML

Agora nós iremos gerar o HTML da documentação gerada.

Essa parte é bem simples, e precisamos de apenas um comando para isso!

Nós vamos utilizar o make, e como argumento, passamos o output da nossa documentação, que neste caso, será html.


E pronto! Temos a nossa documentação gerada, pronta para uso!

sphinx primeira pagina

Conclusão

Gerar documentação automaticamente utilizando o Sphinx é bem tranquilo e fácil, além de mostrar um profissionalismo muito grande nos seus projetos.

Basicamente, tudo o que precisamos aprender para trabalhar com o Sphinx é como formatar o nosso código utilizando o reStructuredText, que também não é uma tarefa de outro mundo!

Note que praticamente todos os projetos de respeito criados em Python possuem uma excelente documentação, e na grande maioria das vezes, gerada através do Sphinx.

E você, o que achou deste tutorial Sphinx? Ficou alguma dúvida, sugestão ou crítica?!

Não deixe de comentar abaixo a sua opinião!

Um grande abraço, e até o próximo artigo!

Links Importantes e Referências




Leave a Reply