Em uma apresentação do Luciano Ramalho, observei que estava utilizando o Sphinx (não confunda com o SphinxSearch) para gerar sua documentação e apresentação. Logo que voltei para o escritório, resolvir dar uma fuçada na ferramenta e simplesmente caiu como uma luva. É uma maneira bastante simples de criar documentações, principalmente de projetos desenvolvidos em Python. Sempre utilizei diversas técnicas para documentar meus projetos, desde Wiki, Texinfo e até LaTex, mas só de pensar em criar toda uma documentação em LaTeX, desanima um pouco.

O Sphinx nada mais é que uma ferramenta que pega um documento escrito em reStrucutredText, compila e gera saída em diversos formatos, como html e até mesmo LaTeX (que pode ser facilmente transformado em PDF). É realmente muito rápido e simples criar uma documentação, que pode estar dentro dos códigos Python. A linguagem de marcação “rst” é simples de ser lida e escrita, não tem todas as complexidades (embora bem completas) de um LaTeX.

Passei a fazer um teste com a ferramenta e adotei em alguns projetos, depois de um tempo utilizando, já posso afirmar que é bem simples e eficiente e toda documentação (que são arquivos texto, seguindo marcação rst) pode ser facilmente controlada por um Bazaar ou SVN (ou outro de sua preferência).

Se você gosta de Emacs, existe um suporte rst para Emacs, o que torna a tarefa de documentar ainda mais facil. Com vários atalhos e funcionalidades, documentar nunca foi tão rápido e menos chato.

Mais informações: Sphinx Python Documentation Generator