Coordenei documentação em Sphinx em várias empresas, cobrindo mais de 100 serviços diferentes no total. O site de documentação do Sphinx é há anos meu manual de referência, e o TechWriters.ru também funcionou nesse mecanismo até agosto de 2026. toctree, include, papéis, domínios, temas e avisos de build vêm de projetos reais.
A experiência explica o tema, não a nota. Portal e repositório foram avaliados como produto documental: entrada, estrutura, referência, exemplos, reutilização, build, busca, versões, interface e tradução.
Escopo da pesquisa
Retrato de 17 de agosto de 2026 no site master e no diretório doc/ do repositório oficial no commit e44a40e. As contagens vêm do código-fonte e a avaliação editorial das páginas publicadas.
arquivos .rst com histórico de releases
arquivos .rst fora de changes/
palavras e tokens segundo wc -w
extensões integradas ativadas
tipos de builder documentados
Um projeto compacto cobre um produto enorme
O conjunto inclui início, uso, extensão, API do Sphinx, comandos, configuração, formatos, FAQ e histórico completo.
| Necessidade | Seção | Resultado |
|---|---|---|
| Começar | Getting started e tutorial completo | Orientação curta e projeto guiado com narrativa e API. [S2] |
| Usar | reStructuredText, Markdown, links, configuração, builders e domínios | Manual completo até internacionalização. [S3] |
| Estender | Tutoriais, procedimentos e API | Papéis, diretivas, eventos, domínios, parsers, temas e testes. [G3] |
| Manter | Comunidade, contribuição, releases e FAQ | Operação do projeto e respostas acumuladas que pedem limpeza. [S11] |
| Consultar | Comandos, conf.py, extensões, glossário e changelog | Profundidade de referência excepcional. [S1] |
Os desenvolvedores usam Sphinx como bancada de testes
Configuração e fontes mostram quase todo o repertório típico.
Estrutura
[G3]35 toctree ligam documentos e a página inicial separa quatro grupos.
Reutilização
[S4]Há include e 31 literalinclude lendo arquivos Python reais.
API do código
[G2]autodoc e autosummary estão ativos, com 13 automodule, 75 autoclass e 18 autofunction.
Entre projetos
[S9]intersphinx conecta Python, Requests e Read the Docs.
Diagramas
[G2]Graphviz e diagramas de herança mostram fases, eventos e classes.
Versões
[S12]612 versionadded, 252 versionchanged e 18 deprecated acompanham a API.
Formatos
[S6]21 builders são documentados e o projeto prepara HTML, PDF, ePub, man e Texinfo.
Validação
[G2]nitpicky, coverage, tipos de aviso e linkcheck transformam o build em controle de qualidade.
Reutilização explica parte da força do reStructuredText
Uma seção comum pode entrar em vários guias, ser limitada por marcadores e variar por builder. literalinclude, only, rst_prolog e rst_epilog completam o modelo.
include
Insere um fragmento .rst compartilhado ou uma seção marcada.
literalinclude
Lê código de um arquivo real e evita divergências.
only
Varia conteúdo por builder ou tag.
rst_prolog e rst_epilog
Adicionam definições e inclusões globais.
Uma seção, dois guias
.. include:: _shared/security-note.rst
:start-after: .. security-start
:end-before: .. security-end_shared/security-note.rst permanece como fonte única e as duas páginas recebem a mesma correção.
Avaliação editorial: 78 de 100
Referência, reutilização e engenharia recebem nota máxima. Interface e tradução reduzem o resultado.
78/100
A jornada é coerente, mas começa duas vezes
A página inicial separa bem início, guia, comunidade e referência. Getting started e Build your first project se sobrepõem sem distinguir claramente caminho rápido e tutorial completo.
| Observação | Evidência | Conclusão |
|---|---|---|
| Mapa sólido | Quatro grupos revelam os tipos de conteúdo. | A arquitetura fica clara na entrada. [S1] |
| Tutorial prático | Uma biblioteca fictícia liga narrativa e API. | Um exemplo contínuo ensina melhor. [S2] |
| Duas entradas | Parte dos fundamentos se repete. | Nomear caminho rápido e tutorial completo. [S1] |
| Final incompleto | Quickstart termina em More topics to be covered. | Resíduo de rascunho enfraquece a página. [S1] |
| Revisão irregular | A abertura mantém Add documentation translations multiple languages. | Falta uma preposição na vitrine. [S1] |
| FAQ envelhecido | Epydoc, SCons, hospedagem antiga do PyPI e _gaq continuam. | Separar respostas históricas do suporte atual. [S11] |
A interface mostra a idade do projeto
Navegação, busca, índice, fonte e versões funcionam. O tema sphinx13 é denso e o painel escuro do Read the Docs parece sobreposto.
Funciona
Árvore, âncoras, índice, busca, fonte e versões.
Envelheceu
Tipografia densa, links pequenos, barra cheia e painel RTD separado.
Confunde
Russo, alemão e francês foram testados: nenhum está completo. Russo e alemão ficam quase inteiramente em inglês; francês alterna tradução e parágrafos ingleses.
Prioridade
Mostrar cobertura da tradução e modernizar sem perder navegação profunda.
Práticas que vale adotar
| Prática | Adotar |
|---|---|
| Links semânticos | Referenciar objetos e seções por identificadores. |
| Fragmentos comuns | Reutilizar avisos e requisitos com include. |
| Exemplos vivos | Ler código testado com literalinclude. |
| Notas de versão | Colocar mudanças e depreciações junto da API. |
| Build rígido | Validar avisos, links e referências em CI. |
| Vários formatos | Gerar PDF, man ou ePub da mesma fonte. |
| Localização honesta | Não apresentar tradução parcial como concluída. |
Fontes da pesquisa
Conclusão: excelente engenharia numa vitrine envelhecida
Sphinx documenta a si próprio quase exemplarmente e usa hierarquia, reutilização, links semânticos, API gerada, diagramas e múltiplas saídas.
A fragilidade está na leitura: interface antiga, início duplicado, resíduos de rascunho, FAQ histórico e seletor de idiomas otimista demais.
A admiração permanece. Sphinx ainda oferece uma combinação rara de estrutura, reutilização e disciplina de build.
O portal comprova a força do Sphinx e mostra como a engenharia pode avançar mais rápido que a apresentação.