Como usamos Sphinx para documentar projetos Python

O Sphinx é uma ferramenta para facilitar a criação de documentações inteligentes e apresentáveis. Originalmente foi criado para documentar o novo Python 2.7, e por isso tem um excelente suporte para documentar projetos Python.

Dentre as inúmeras vantagens da ferramenta, o que mais nos chamou a atenção foi:

  • A usabilidade do site que o Sphinx gera;
  • A possibilidade de gerar documentação a partir de docstrings no código do projeto;
  • Facilidade de organizar e adicionar conteúdo à documentação, a partir de arquivos textos escritos em reStructuredText.

Continue Reading…

Adding SVG support to Sphinx’s Graphviz extension

Sphinx has a few built-in extensions to take your documentation one step further. Among all, I’ve been finding the Graphviz extension very useful. It enables the use of DOT language to describe a graph that will be converted into a PNG image by Graphviz.

For some reason, the Graphviz version installed on my Mac is generating corrupted PNG files. Fortunately, it supports many other formats including SVG which has the greatest results. Continue Reading…