Tutorial: Construa seu primeiro projeto

Neste tutorial você construirá um projeto de documentação simples usando o Sphinx e o visualizará em seu navegador como HTML. O projeto incluirá documentação narrativa e manuscrita, bem como documentação de API gerada automaticamente.

O tutorial é voltado para iniciantes no Sphinx que desejam aprender os fundamentos de como os projetos são criados e estruturados. Você criará uma biblioteca fictícia de software para gerar receitas de alimentos aleatórias que servirão de guia durante todo o processo, com o objetivo de documentá-lo adequadamente.

Para demonstrar os recursos do Sphinx para documentação de código, você usará Python, que também oferece suporte à geração automática de documentação.

Nota

Várias outras linguagens são suportadas nativamente no Sphinx para documentação de código manual, porém elas requerem extensões para documentação de código automática, como Breathe.

Para seguir as instruções, você precisará de acesso a uma linha de comando semelhante ao Linux e um entendimento básico de como ela funciona, bem como uma instalação funcional do Python para desenvolvimento, já que você usará ambientes virtuais Python para criar o projeto.

• Primeiros passos
  • Configurando seu projeto e ambiente de desenvolvimento
  • Criando o layout da documentação
• Primeiros passos para documentar seu projeto usando Sphinx
  • Building your HTML documentation
  • Building your documentation in other formats
• Mais personalização do Sphinx
  • Enabling a built-in extension
  • Using a third-party HTML theme
• Documentação narrativa no Sphinx
  • Structuring your documentation across multiple pages
  • Adding cross-references
• Descrevendo código no Sphinx
  • Python
    • Documenting Python objects
    • Referência cruzada de objetos Python
    • Including doctests in your documentation
  • Other languages (C, C++, others)
    • Documenting and cross-referencing objects
      • CustomList
• Geração automática de documentação a partir do código
  • Reutilizando assinaturas e docstrings com autodoc
  • Gerando referências de API abrangentes
• Apêndice: Fazendo deploy de um projeto Sphinx online
  • Sphinx-friendly deployment options
  • Embracing the “Docs as Code” philosophy
  • Publishing your documentation sources
    • GitHub
    • GitLab
  • Publishing your HTML documentation
    • Read the Docs
    • GitHub Pages
    • GitLab Pages
• Aonde ir a partir daqui