Sphinx transforma arquivos de texto e informações do código em documentação navegável. Para um projeto Python pequeno, o fluxo necessário é direto: instalar Sphinx, executar sphinx-quickstart, escrever uma página inicial, habilitar autodoc, gerar HTML e publicar. Não é preciso começar com dezenas de extensões, um tema personalizado ou uma arquitetura de documentação complexa.

Este guia cria uma base sustentável para uma biblioteca com layout src. Ela combina explicações escritas por pessoas com uma referência de API extraída de docstrings e type hints em Python.

Estrutura do projeto e instalação

Partimos desta estrutura:

calculadora/
├── docs/
├── src/
│   └── calculadora/
│       ├── __init__.py
│       └── operacoes.py
├── tests/
└── pyproject.toml

Use um ambiente virtual e instale Sphinx. Instalar o próprio pacote em modo editável permite que autodoc o importe sem alterar sys.path em conf.py:

python -m pip install -e .
python -m pip install sphinx

Registre Sphinx nas dependências de documentação do projeto para que colegas e CI usem a mesma faixa de versões. Dependendo do gerenciador, isso pode ser um extra em pyproject.toml ou um docs/requirements.txt pequeno.

Criar a base com sphinx-quickstart

Na raiz, execute:

sphinx-quickstart docs

Responda que deseja separar diretórios de origem e build, informe nome, autor, versão e idioma pt_BR. O comando cria, entre outros arquivos:

docs/
├── Makefile
├── make.bat
├── build/
└── source/
    ├── conf.py
    └── index.rst

As opções podem mudar entre versões, portanto consulte o tutorial oficial do Sphinx. O arquivo conf.py contém configuração Python; index.rst é a página inicial; build/ recebe artefatos e normalmente não deve ser versionado.

Mantenha a configuração inicial curta:

## docs/source/conf.py
project = "Calculadora"
author = "Equipe Calculadora"
release = "1.0.0"
language = "pt_BR"

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
]

html_theme = "alabaster"

autodoc lê objetos Python. napoleon interpreta docstrings nos estilos Google e NumPy. O tema integrado Alabaster é suficiente para começar; um tema externo pode ser adotado depois, quando houver uma necessidade concreta.

Escrever docstrings que explicam contratos

Docstrings devem explicar intenção, parâmetros, retorno, exceções e limitações relevantes. Não repita cada linha da implementação. O PEP 257 define convenções básicas, como uma frase-resumo e a organização de docstrings multilinha.

Com Napoleon habilitado, uma função pode usar estilo Google:

def dividir(dividendo: float, divisor: float) -> float:
    """Divide dois números.

    Args:
        dividendo: Valor que será dividido.
        divisor: Valor pelo qual dividir. Não pode ser zero.

    Returns:
        O quociente dos dois valores.

    Raises:
        ValueError: Se ``divisor`` for zero.
    """
    if divisor == 0:
        raise ValueError("divisor não pode ser zero")
    return dividendo / divisor

As anotações informam tipos, enquanto a docstring explica semântica. Evite escrever o tipo duas vezes se a configuração já mostra type hints; documente o significado, unidades, condições e efeitos colaterais. Docstrings públicas devem acompanhar alterações no comportamento, assim como os testes com pytest.

Gerar referência com autodoc

Crie docs/source/api.rst:

Referência da API
=================

Operações
---------

.. automodule:: calculadora.operacoes
   :members:
   :undoc-members:
   :show-inheritance:

Inclua a página na árvore de navegação de index.rst:

Calculadora
===========

Biblioteca pequena para operações matemáticas previsíveis.

.. toctree::
   :maxdepth: 2
   :caption: Conteúdo

   uso
   api

Crie também uso.rst com instalação, um exemplo mínimo e comportamento esperado. A referência gerada responde “quais objetos existem”; a página narrativa responde “como resolvo uma tarefa”. Uma não substitui a outra.

Durante o build, autodoc importa calculadora.operacoes. Por isso, código executado no topo do módulo também será executado. Evite conexões de rede, leitura obrigatória de variáveis secretas e inicializações caras durante importação. Se uma dependência opcional não estiver disponível, autodoc_mock_imports = ["dependencia"] pode permitir o build, mas simular seu próprio pacote esconderia erros reais.

Consulte a referência oficial do autodoc antes de adicionar opções à diretiva: ela detalha importação, seleção de membros e ordem de exibição.

Gerar HTML e tratar avisos

Na raiz do projeto, execute:

sphinx-build -M html docs/source docs/build

Abra docs/build/html/index.html. Durante desenvolvimento, make -C docs html ou docs\make.bat html são atalhos equivalentes criados pelo quickstart.

Na CI, torne avisos fatais para detectar referências quebradas e erros de docstring:

sphinx-build -W --keep-going -b html docs/source docs/build/html

-W transforma warnings em erro e --keep-going reúne mais problemas antes de encerrar. Use isso desde cedo; ativar somente depois de centenas de páginas torna a limpeza difícil. Não ignore avisos globalmente sem entender a origem.

Erros comuns incluem esquecer de instalar o pacote, colocar uma página fora do toctree, errar a indentação de diretivas RST e importar módulos com efeitos colaterais. Também é comum gerar toda a API e não escrever uma página de uso. A documentação precisa orientar uma tarefa real, não apenas listar assinaturas.

Publicar no Read the Docs

O Read the Docs clona o repositório, instala dependências e executa o build. Adicione um arquivo .readthedocs.yaml mínimo na raiz:

version: 2

sphinx:
  configuration: docs/source/conf.py
  fail_on_warning: true

python:
  install:
    - method: pip
      path: .
    - requirements: docs/requirements.txt

Em docs/requirements.txt, declare a faixa de Sphinx usada. Depois, importe o repositório no serviço e confira o log do primeiro build. A documentação oficial do Read the Docs mostra o processo e a configuração suportada atualmente.

Como alternativa, adicione o comando com -W ao pipeline descrito no guia de GitHub Actions para Python e publique docs/build/html no host estático escolhido. Evite manter dois processos de publicação sem necessidade: escolha Read the Docs ou sua CI como responsável principal.

Referências internas devem usar papéis do Sphinx em vez de URLs relativas sempre que possível. Um rótulo explícito, como .. _instalacao:, permite apontar para uma seção com :ref:\instalacao`mesmo que o arquivo seja movido. Para objetos Python documentados,:class:,:func:` e outros papéis criam links e ajudam o build a detectar nomes incorretos.

O Intersphinx conecta a documentação a inventários de outros projetos, como a biblioteca padrão do Python. Ative sphinx.ext.intersphinx, configure somente fontes confiáveis e confira se os links resolvem durante o build. Essa abordagem é mais sustentável do que copiar explicações externas ou manter links profundos manualmente.

Se houver várias versões públicas da biblioteca, declare qual documentação corresponde à versão estável e como acessar versões antigas. Read the Docs pode manter builds por tag; em hospedagem própria, a CI precisa definir a estrutura de URLs. Não publique automaticamente a documentação da branch principal como se descrevesse a última versão estável. Recursos anunciados antes do lançamento confundem quem instalou o pacote disponível.

Manutenção sem burocracia

Trate documentação e código na mesma mudança. Ao alterar uma função pública, revise sua docstring, a página de uso e o teste relacionado. Uma revisão de pull request pode confirmar três pontos: o exemplo ainda executa, a assinatura gerada corresponde à API e o build não produz warnings. Essa rotina curta evita mutirões posteriores.

Não tente documentar cada função privada. Priorize instalação, primeiro resultado, decisões que surpreendem o usuário e interfaces públicas. Exemplos devem ser pequenos o bastante para serem compreendidos isoladamente e completos o bastante para executar. Se um trecho depende de arquivos ou variáveis de ambiente, diga isso antes do código. Remova páginas obsoletas em vez de mantê-las apenas para aumentar volume: encontrar instruções antigas é pior do que não encontrar uma página.

Checklist e conclusão

  • Instale o pacote e Sphinx em ambiente isolado.
  • Rode sphinx-quickstart docs e mantenha conf.py simples.
  • Habilite autodoc e napoleon somente porque há uso concreto.
  • Escreva docstrings públicas com contratos, retornos e exceções.
  • Combine tutorial de uso com referência automática da API.
  • Gere HTML localmente e corrija todos os warnings.
  • Execute sphinx-build -W --keep-going na CI.
  • Publique por Read the Docs ou por um único fluxo de CI.

O ponto de partida saudável é pequeno: uma página inicial, uma página de uso e uma referência de API. Quando usuários reais pedirem busca melhor, versões ou outro formato, Sphinx permite evoluir. Antes disso, conteúdo correto e build confiável valem mais do que uma coleção de extensões.