Henrique Bastos.NET

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.

Quando o assunto é documentação, é sempre importante ter cuidado para evitar excessos. O ideal é documentar o necessário para desobstruir a Equipe, permitindo que o trabalho flua cada vez mais.

Hoje, nosso objetivo é simplesmente registrar informações que não consultamos toda hora, mas quando precisamos é importante que estejam facilmente acessíveis; como:

• Dependências de outras tecnologias e suas versões;
• Explicação sobre nosso commit pattern;
• Descrição da infra-estrutura dos ambientes, listando máquinas, endereços, serviços contratados, etc;
• Contatos para suporte técnico dos fornecedores diretamente ligados ao projeto;
• Parte do código e ferramentas que criamos para o projeto.

Escolhemos o Sphinx porque a Equipe é formada principalmente por desenvolvedores que estão sempre em contato com o código e o repositório do projeto. Portanto, editar um arquivo texto dentro do diretório docs no projeto tem menor aderência do que, por exemplo, navegar até um wiki, se logar, e então criar e organizar o conteúdo.

Para facilitar o acesso à documentação, criamos um domínio interno onde hospedamos o site gerado pelo Sphinx. O deploy pode ser feito por qualquer pessoa com o comando fab docdeploy, via Fabric, e para ver a documentação basta digitar “projetodoc” no browser.

[]‘s!