pydoc no Python: documentação automática

Docstrings bem escritas podem virar ajuda interativa, páginas de terminal e arquivos HTML sem instalar ferramentas externas. O módulo pydoc no Python inspeciona módulos, classes, funções e métodos e gera documentação com base no atributo __doc__, nas assinaturas e nos membros disponíveis.

O pydoc é útil para explorar bibliotecas, revisar APIs internas, criar documentação rápida e entender objetos durante o desenvolvimento. Ele não substitui necessariamente sistemas completos como Sphinx ou MkDocs e exige cuidado porque importa os módulos analisados, executando código de nível superior. Neste guia você aprenderá comandos, docstrings, HTML, busca, servidor local, integração com help() e práticas seguras.

O conteúdo complementa nossos artigos sobre inspect, types, sysconfig, platform e py_compile.

Como o pydoc encontra documentação

Para módulos, classes, funções e métodos, pydoc lê a docstring do objeto e percorre membros documentáveis. Quando uma docstring não existe, ele pode tentar obter um bloco de comentários imediatamente anterior à definição usando recursos do módulo inspect.

Docstrings são a fonte mais previsível. Comentários comuns devem explicar implementação; docstrings devem descrever o contrato público.

Uma docstring simples

def calcular_total(valores, taxa=0):
    """Calcula a soma dos valores e aplica uma taxa percentual.

    Args:
        valores: Sequência de números.
        taxa: Percentual adicional.

    Returns:
        Total calculado.
    """
    subtotal = sum(valores)
    return subtotal * (1 + taxa / 100)

Pydoc mostra o texto e a assinatura. Ele não valida se a documentação corresponde ao comportamento real, portanto testes e revisão continuam necessários.

Usar help no interpretador

help(calcular_total)
help("json")
help(str.split)

A função built-in help() usa o sistema do pydoc para gerar texto no console. Ela aceita objetos ou nomes pesquisáveis.

Executar pydoc no terminal

python -m pydoc json
python -m pydoc pathlib.Path
python -m pydoc meu_pacote.modulo.funcao

O argumento pode ser módulo, pacote, classe, método, função ou referência pontuada. O resultado se parece com uma página de manual.

Documentar um arquivo por caminho

Se o argumento contém o separador de caminhos e aponta para um arquivo Python existente, pydoc pode documentar esse arquivo.

python -m pydoc ./ferramentas/relatorio.py

Use caminhos controlados. Não permita que usuários escolham arquivos arbitrários em um serviço.

Atenção: pydoc importa módulos

Para encontrar objetos, pydoc importa o módulo. Todo código de nível superior pode ser executado.

# Evite efeitos no import
conexao = abrir_conexao_producao()
iniciar_worker()

Um módulo documentado dessa forma poderia abrir conexões, iniciar threads, alterar arquivos ou enviar requisições.

Proteção com __main__

def main():
    executar_aplicacao()


if __name__ == "__main__":
    main()

Coloque ações de execução sob o guard. Imports devem definir objetos e realizar apenas inicialização mínima e segura.

Imports também podem falhar

Dependências ausentes, variáveis de ambiente obrigatórias e bibliotecas nativas incompatíveis podem impedir a geração. Projete módulos para que a importação seja previsível e apresente mensagens claras.

Paginação no terminal

Ao mostrar texto longo, pydoc tenta usar um paginador. As variáveis MANPAGER e PAGER podem selecionar o programa, com prioridade para MANPAGER.

Em CI ou redirecionamento para arquivo, o comportamento pode ser diferente. Não dependa de interação.

Gerar HTML

python -m pydoc -w meu_pacote

A opção -w grava documentação HTML no diretório atual. Confirme o diretório de trabalho e permissões antes de executar.

Arquivos existentes podem ser substituídos dependendo do nome. Gere em um diretório de build limpo.

Documentar vários módulos

python -m pydoc -w pacote.modulo_a pacote.modulo_b

Para um site grande, um gerador dedicado oferece navegação, temas, referências cruzadas e pipeline de publicação mais controlados.

Pesquisar módulos por palavra

python -m pydoc -k database

A opção -k pesquisa a linha de sinopse dos módulos disponíveis. A sinopse é normalmente a primeira linha da docstring do módulo.

Escreva uma primeira linha curta e informativa.

Docstring de módulo

"""Gera relatórios financeiros em CSV e PDF.

Este módulo contém validadores, formatadores e exportadores.
"""

A linha inicial ajuda a busca e os índices. Separe-a do restante com uma linha vazia.

Servidor HTTP local

python -m pydoc -p 1234

O comando inicia um servidor em localhost. A porta zero escolhe uma porta livre.

python -m pydoc -p 0

A interface permite navegar por módulos, tópicos e palavras-chave.

Abrir o navegador automaticamente

python -m pydoc -b

A opção inicia o servidor e abre a página de índice no navegador padrão.

Escolher hostname

python -m pydoc -n 0.0.0.0 -p 8000

Alterar o host pode tornar o serviço acessível por outras máquinas, útil em um container de desenvolvimento. Isso aumenta a exposição.

Servidor não é para produção

A documentação oficial avisa que o servidor HTTP é destinado ao desenvolvimento local. Ele não oferece o conjunto de autenticação, autorização, TLS, limites, hardening e observabilidade esperado em produção.

Não exponha módulos internos ou segredos da aplicação em redes públicas.

O ambiente define o que será documentado

Pydoc usa o sys.path e o ambiente atuais. O comando documenta a mesma versão que seria importada naquele interpretador.

Ative o virtualenv correto e confirme o executável:

python -c "import sys; print(sys.executable)"
python -m pydoc meu_pacote

Pacotes com versões múltiplas

Se há instalações globais e virtuais, chamar apenas pydoc pode usar outro Python. Prefira python -m pydoc com o interpretador desejado.

PYTHONDOCS

Para módulos da biblioteca padrão, pydoc presume que a documentação oficial está em docs.python.org/X.Y/library/. A variável PYTHONDOCS pode apontar para outra URL ou para um diretório local.

Valide a origem em ambientes controlados para evitar links incorretos.

Assinaturas de funções

Pydoc usa inspect.signature() para extrair assinaturas de callables.

Decorators mal implementados podem esconder a assinatura. Use functools.wraps() para preservar metadados.

from functools import wraps


def registrar(funcao):
    @wraps(funcao)
    def wrapper(*args, **kwargs):
        return funcao(*args, **kwargs)
    return wrapper

Classes e herança

A documentação de uma classe mostra métodos, atributos e hierarquia detectável. Mantenha docstrings de classe focadas na responsabilidade, invariantes e forma de criação.

class Cliente:
    """Representa um cliente validado da aplicação."""

Propriedades e descriptors

Properties e descriptors podem aparecer com sua documentação. Evite efeitos colaterais em introspecção e mantenha o acesso ao objeto de classe seguro.

Type hints

Anotações ajudam leitores, mas pydoc não substitui um verificador estático. Documente unidades, faixas, exceções e efeitos que o tipo não expressa.

Exceções

Uma docstring útil informa erros previsíveis.

def dividir(a, b):
    """Divide a por b.

    Raises:
        ZeroDivisionError: Se b for zero.
    """
    return a / b

APIs públicas e privadas

Nomes iniciados por underscore comunicam uso interno, mas pydoc pode ainda encontrar membros. Defina __all__ e organize a API pública de forma clara.

Docstrings não devem conter segredos

Não inclua tokens, URLs privadas, credenciais de exemplo reais ou detalhes de infraestrutura. A documentação pode ser gerada e compartilhada automaticamente.

Conteúdo executável em exemplos

Exemplos em docstrings devem ser seguros e determinísticos. O pydoc apenas exibe o texto; doctest pode executá-lo separadamente.

Testar documentação

Uma etapa de CI pode importar módulos e gerar HTML para detectar falhas.

python -m pydoc -w meu_pacote.modulo

Execute em ambiente isolado, sem credenciais de produção e com rede bloqueada quando apropriado.

pydoc versus Sphinx

Pydoc é excelente para inspeção rápida e documentação de referência simples. Sphinx oferece páginas narrativas, referências cruzadas, extensões, temas e publicação estruturada.

Os dois podem coexistir: docstrings boas beneficiam pydoc, IDEs e geradores maiores.

pydoc versus help

help() é a interface interativa dentro do Python. python -m pydoc oferece terminal, busca, HTML e servidor.

Erros frequentes

• Executar efeitos de produção durante import.
• Gerar documentação com o Python errado.
• Expor o servidor HTTP em rede pública.
• Escrever docstrings sem primeira linha clara.
• Perder assinaturas em decorators.
• Incluir segredos em exemplos.
• Presumir que pydoc valida a documentação.
• Gerar HTML no diretório errado.

Boas práticas

• Mantenha imports seguros e leves.
• Use o guard __main__.
• Execute com python -m pydoc.
• Ative o ambiente correto.
• Use docstrings focadas no contrato.
• Preserve assinaturas com wraps.
• Restrinja o servidor ao desenvolvimento.
• Teste a geração em CI isolado.

Conclusão

O módulo pydoc no Python transforma docstrings e introspecção em ajuda de terminal, HTML, busca e navegação local. Ele é uma ferramenta prática para explorar APIs e criar documentação de referência rapidamente.

Seu funcionamento depende de importar o código. Por isso, módulos devem ser seguros no import e o servidor deve permanecer em desenvolvimento local. Consulte a documentação oficial de pydoc e a PEP 257 sobre convenções de docstrings para produzir documentação mais clara.