Quando o seu conjunto de documentação é grande ou você sente a necessidade de maior organização e estrutura, pode ser útil usar um motor de documentação ao invés de trabalhar apenas com arquivos de texto.
Um motor de documentação (documentation engine) recebe arquivos de texto puro em um formato especial (por exemplo, reStructuredText ou markdown) e gera uma saída legível (HTML, PDF, ePub, etc). Ele também pode fornecer funcionalidades adicionais, como navegação, busca, indexação, temas visuais, entre outros.)
Vamos discutir dois motores populares na comunidade Python: Sphinx e MkDocs.
Sphinx¶
Documentação oficial do Sphinx
Pontos fortes:
- Muito usado na comunidade Python (documentação do Python, NumPy, SciPy, Pandas, Matplotlib, etc)
- Flexível e extensível, com muitas extensões disponíveis
- Suporte nativo para docstrings e geração automática de documentação de APIs com autodoc
- Suporte para múltiplos formatos de saída (HTML, PDF, ePub, etc)
- Poderoso e robusto: projeto maduro e estável
Pontos fracos:
- Curva de aprendizado mais íngreme
- Baseado em docutils e reStructuredText, que podem ser menos familiares para novos usuários
Exemplo:
MkDocs¶
Documentação oficial do MkDocs
Moderno, bonito e fácil de usar, focado em documentação escrita em Markdown.
Pontos fortes:
- Fácil de configurar e usar, com uma curva de aprendizado suave
- Focado em Markdown, um formato amplamente usado e fácil de aprender
- Temas visuais modernos e atraentes, como o Material for MkDocs
- Suporte para plugins para estender funcionalidades
Pontos fracos:
- Menos flexível que o Sphinx para projetos complexos
- Menos extensões disponíveis em comparação com o Sphinx
Exemplo:
Bônus: MyST¶
- Documentação oficial do MyST-md, também conhecido como MyST JS
- Documentação oficial do MyST Parser (usado com Sphinx)
Bônus: Jupyter Book¶
- Documentação oficial do Jupyter Book
- Esse tutorial foi escrito com o Jupyter Book! Veja o repositório do tutorial
Bônus: Quarto¶
- Documentação oficial do Quarto
- Suporta múltiplas linguagens (R, Python, Julia, Observable)
- Focado em ciência de dados e publicação acadêmica, mas pode ser usado para documentação geral
- Inclui ferramentas para documentação executável
Bônus: Docusaurus¶
- Documentação oficial do Docusaurus
- Baseado em React, focado em documentação de projetos JavaScript/TypeScript, mas pode ser usado para qualquer projeto.