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.

To add SVG format support into sphinx.ext.graphviz, I had to do a little refactoring:

  1. Moved the default hardcoded PNG format to a configuration variable named graphviz_output_format;
  2. Render the object tag to display SVG files properly on Firefox and Safari.

I had to use the object tag because Firefox can’t render SVG with the img tag. Read more about cross browsing SVG issues.

To use it, follow these steps:

  1. Create an _ext subdirectory on your Sphinx project;
  2. Download the modified extension from Gist and save it to _ext;
  3. Edit your config.py and make sure it contains the below lines;


O Sphinx vem com algumas extensões para tornar o resultado final da documentação ainda mais interessante. A extensão do Graphviz vem se revelando bastante útil para mim. Ela possibilita a descrição de um grafo em linguagem DOT, que no documento final será substituída por uma imagem PNG gerada pelo Graphviz.

Por algum motivo, todos os arquivos PNG gerados pela versão do Graphviz instalada no meu Mac ficam corrompidos. Felizmente o Graphviz suporta outros formatos, dentre os quais o SVG tem um resultado simplesmente fantástico.

Para adicionar o suporte ao formato SVG na extensão sphinx.ext.graphviz, fiz uma simples refatoração no código para:

  1. Mover a definição padrão do formato PNG que estava hardcoded para a opção de configuração graphviz_output_format;
  2. Adicionar a renderização da tag object para exibir a imagem SVG corretamente no Firefox e no Safari.

Precisei usar a tag object, pois o Firefox não exibe SVG através da tag img. Leia mais sobre esse inconveniente.

Para usar a extensão, basta:

  1. Criar um subdiretório _ext no seu projeto Sphinx;
  2. Fazer download do código da extensão modificada no Gist e salvá-lo no diretório _ext;
  3. Editar o config.py do seu projeto Sphinx para conter as linhas abaixo:

[]’s!