Criando Documentação Automática com Sphinx em Python
No ecossistema Python, a ferramenta mais usada para documentação automática é o Sphinx. Neste artigo vamos aprender:
O que é o Sphinx.
Como instalar e configurar em um projeto Python.
Como gerar documentação automaticamente a partir de docstrings.
Como exportar em diferentes formatos (HTML, PDF, etc.).
🔹 1. O que é o Sphinx?
O Sphinx é uma ferramenta de geração de documentação escrita originalmente para os manuais do Python.
Ele converte arquivos de texto estruturados (em reStructuredText ou Markdown) em documentação elegante e navegável.
Alguns destaques:
Integração com docstrings do Python.
Geração de documentação em HTML, PDF, ePub e outros formatos.
Suporte a extensões (como
sphinx.ext.autodoc,sphinx.ext.napoleonpara Google/NumPy style docstrings).Muito usado em projetos open source e empresas.
🔹 2. Instalando o Sphinx
No seu ambiente virtual Python, rode:
pip install sphinx
Opcionalmente, instale também o sphinx-rtd-theme, que é o tema usado pelo famoso Read the Docs:
pip install sphinx-rtd-theme
🔹 3. Estrutura inicial do projeto
Vamos criar um pequeno projeto Python chamado calculadora com algumas funções simples:
📂 Estrutura inicial:
meu_projeto/
│── calculadora/
│ ├── __init__.py
│ ├── operacoes.py
│── docs/
│── requirements.txt
📄 Arquivo operacoes.py:
"""
Módulo de operações matemáticas simples.
"""
def somar(a, b):
"""
Soma dois números.
:param a: Primeiro número.
:param b: Segundo número.
:return: Resultado da soma.
"""
return a + b
def dividir(a, b):
"""
Divide um número pelo outro.
:param a: Numerador.
:param b: Denominador (não pode ser zero).
:raises ZeroDivisionError: Se b for zero.
:return: Resultado da divisão.
"""
if b == 0:
raise ZeroDivisionError("Divisão por zero não permitida")
return a / b
🔹 4. Inicializando o Sphinx
No diretório raiz (meu_projeto), rode:
sphinx-quickstart
Você será perguntado sobre algumas opções:
Root path for the documentation →
docsSeparate source and build directories →
y(boa prática separar)Project name →
CalculadoraAuthor name → Seu nome
Project release →
0.1
Isso criará dentro de docs/ uma estrutura parecida:
docs/
│── build/ ← onde vai sair a doc pronta
│── source/ ← arquivos fonte da documentação
│ ├── conf.py ← configurações
│ ├── index.rst
🔹 5. Configurando o conf.py
Edite o arquivo docs/source/conf.py para incluir:
import os
import sys
sys.path.insert(0, os.path.abspath('../../'))
# Ativar extensões úteis
extensions = [
'sphinx.ext.autodoc', # extrai docstrings
'sphinx.ext.napoleon', # suporta Google/NumPy style docstrings
]
# Usar tema Read the Docs
html_theme = 'sphinx_rtd_theme'
🔹 6. Gerando documentação automática
Para documentar o módulo calculadora, execute dentro da pasta docs/source:
sphinx-apidoc -o . ../../calculadora
Isso vai criar arquivos .rst para cada módulo detectado.
Exemplo: calculadora.rst terá referências às funções somar e dividir.
Agora, edite o index.rst para incluir o módulo:
.. Calculadora documentation master file
Bem-vindo à documentação da Calculadora!
========================================
.. toctree::
:maxdepth: 2
:caption: Conteúdo:
calculadora
🔹 7. Compilando a documentação
Dentro da pasta docs, rode:
make html
Ou, no Windows:
.\make.bat html
A documentação será gerada em docs/build/html/.
Abra index.html no navegador e você verá sua doc pronta! 🎉
🔹 8. Exportando para PDF (LaTeX)
Se tiver LaTeX instalado, pode gerar PDFs:
make latexpdf
Isso cria um manual em PDF com toda a documentação formatada.
🔹 9. Publicando no Read the Docs
O Read the Docs é uma plataforma que compila automaticamente a documentação do seu projeto hospedado no GitHub/GitLab/Bitbucket.
Basta:
Subir o código e a pasta
docs/no GitHub.Conectar o repositório ao Read the Docs.
Ele automaticamente compila e hospeda sua documentação online.
Exemplo: https://seuprojeto.readthedocs.io/
🔹 10. Boas práticas na documentação
✔️ Escreva docstrings claras em todas as funções e classes.
✔️ Use Google Style ou NumPy Style, suportados pelo napoleon.
✔️ Mantenha a documentação atualizada conforme o código evolui.
✔️ Use exemplos de uso (Examples) dentro das docstrings.
✔️ Integre a documentação no seu pipeline de CI/CD.
🔹 11. Exemplo de docstring no estilo Google
def multiplicar(a, b):
"""
Multiplica dois números.
Args:
a (int ou float): Primeiro número.
b (int ou float): Segundo número.
Returns:
int ou float: Resultado da multiplicação.
Example:
>>> multiplicar(2, 3)
6
"""
return a * b
✅ Conclusão
O Sphinx é a ferramenta ideal para gerar documentação profissional e automatizada em projetos Python. Ele combina:
Formatos diversos (HTML, PDF, ePub)
Com ele, você mantém sua base de código bem documentada, o que facilita a colaboração e aumenta a credibilidade do seu projeto.
Comentários
Postar um comentário