Python Brasil 2022

Decifrando o Sphinx: os enigmas da documentação técnica
2022-10-23 , Aruanã - Vasco Vasquez

Vamos falar sobre o Sphinx para documentação técnica, incluindo a utilização de extensões para documentação automática, boas práticas e alguns exemplos de ferramentas adicionais como o MyST.


O Sphinx, baseado na linguagem de marcação reStructuredText, é o sistema de geração de documentação técnica mais utilizado no mundo Python. Ele fornece flexibilidade e recursos avançados para a criação de documentação de API ou narrativa para projetos de software. Nesta palestra, vamos discutir alguns detalhes sobre a utilização do Sphinx para gerar documentação, incluindo a utilização de algumas extensões para documentar classes e módulos automaticamente. Também discutiremos boas práticas para facilitar a manutenção da documentação em projetos grandes e algumas aplicações avançadas para gerar tabelas de funções e métodos e galerias de exemplos. Por fim, vamos analisar alguns exemplos práticos de ferramentas para usar em conjunto com Sphinx, incluindo o MyST, que permite utilizar Markdown para a formatação do texto gerado.

  • Apresentação (5 min)
  • Introdução à documentação técnica (10 min)
  • Sphinx e extensões (10 min)
  • Exemplo prático (10 min)
  • Conclusão (5 min)

Link: https://www.youtube.com/watch?v=azbJ_CvacbQ

Melissa é matemática e trabalha com desenvolvimento de software na Quansight. É líder do time de documentação do NumPy, entusiasta de Python, LaTeX, Fortran e software livre em geral.