Documentação simples e sofisticada com Sphinx

Tornando a documentação eficaz e fácil de escrever

Saiba como criar documentos fáceis de manter e guiados por estilo que podem ser distribuídos automaticamente em diferentes formatos, como HTML, usando a ferramenta Sphinx.

Alfredo Deza, Software Engineer

Photo of Alfredo DezaAlfredo Deza é engenheiro de software, ex-atleta profissional e olímpico com forte formação em administração de sistema. Ele é apaixonado por software livre e é orador regular em grupos de tecnologia local e conferências internacionais, como a PyCon. Em seu tempo livre, ele tenta melhorar suas habilidades com a fotografia e gosta de contribuir para projetos de software livre.



15/Dez/2011

Introdução

Sphinx é uma ferramenta que permite que desenvolvedores criem documentação em texto simples para geração fácil de saída em formatos que atendem a necessidades variadas. Isso é útil ao usar um Sistema de Controle de Versão para controlar mudanças. Documentação em texto simples também é útil para colaboradores em diferentes sistemas. Texto simples é um dos formatos mais móveis disponíveis atualmente.

Embora o Sphinx tenha sido escrito em Python e tenha sido originalmente criado para a documentação da linguagem Python, não é necessariamente centrado em linguagem e, em alguns casos, nem mesmo específico para programadores. Há muitos usos para o Sphinx, como escrever livros inteiros!

Destaque

Sphinx tem destaque de código para Python por padrão, mas também permite definição de outras linguagens de programação como C e Ruby.

Pense no Sphinx como sendo uma estrutura de documentação: ele abstrai as partes tediosas e oferece funcionalidade automática para resolver problemas comuns, como indexação de título e destaque de código especial (se estiver mostrando exemplos de código) com destaque de sintaxe apropriado.

Requisitos

Você deve se sentir confortável em usar um terminal do Linux® ou UNIX® (também chamado de console ou emulador de terminal), pois a interface de linha de comando é a maneira primária de interagir com o Sphinx.

Python precisa estar instalado. Ele vem pré-instalado e pronto para usar em todas as principais distribuições do Linux e em alguns sistemas operacionais baseados em UNIX (como Mac OSX). Sphinx deve funcionar com Python versões 2.4, 2.5 e 2.6. Para garantir que você tenha Python e uma versão válida, execute o comando na Listagem 1.

Listagem 1. Verificando a versão do Python
$ python --version
Python 2.6.1

Sintaxe

Sphinx usa sintaxe de marcação reStructuredText (com algumas adições) para fornecer controle de documento. Se você já escreveu arquivos de texto simples, provavelmente já sabe bastante sobre a sintaxe necessária para ser proficiente em Sphinx.

A marcação permite definição e estrutura do texto para a saída apropriada. Antes de começar, consulte a Listagem 2 para ver um pequeno exemplo da sintaxe de marcação.

Listagem 2. Exemplo da sintaxe de marcação do Sphinx
This is a Title
===============
That has a paragraph about a main subject and is set when the '='
is at least the same length of the title itself.

Subject Subtitle
----------------
Subtitles are set with '-' and are required to have the same length 
of the subtitle itself, just like titles.

Lists can be unnumbered like:

 * Item Foo
 * Item Bar

Or automatically numbered:

 #. Item 1
 #. Item 2

Inline Markup
-------------
Words can have *emphasis in italics* or be **bold** and you can define
code samples with back quotes, like when you talk about a command: ``sudo`` 
gives you super user powers!

Como se pode ver, a sintaxe é fácil de ler em texto simples. Quando chegar a hora de criar um formato específico (como HTML), o título será um cabeçalho superior e terá uma fonte maior que o subtítulo (como deve ser), e as listas numeradas serão apropriadamente numeradas. Você já tem algo bem eficiente. Incluir mais itens ou alterar a ordem na lista numerada não afeta a numeração, e é possível mudar a importância dos títulos substituindo o sublinhado usado.

Instalação e configuração

A instalação ocorre na linha de comando e é simples, como mostra a Listagem 3.

Listagem 3. Instalando Sphinx
$ easy_install sphinx
Searching for sphinx
Reading http://pypi.python.org/simple/sphinx/
Reading http://sphinx.pocoo.org/
Best match: Sphinx 1.0.5
Downloading http://pypi.python.org/packages/[...]
Processing Sphinx-1.0.5-py2.5.egg
[...]
Finished processing dependencies for sphinx

Listagem 3 foi abreviada, mas dá um exemplo do que esperar ao instalar o Sphinx.

A estrutura usa uma estrutura de diretório para ter separação entre a fonte (os arquivos de texto simples) e o desenvolvimento (que se refere à saída gerada). Por exemplo, se o Sphinx for direcionado para gerar um PDF a partir de uma origem de documentação, o arquivo seria colocado no diretório de desenvolvimento. Esse comportamento pode ser alterado, mas, por consistência, iremos continuar com o formato padrão.

Vamos começar rapidamente um novo projeto de documentação na Listagem 4 que irá solicitar algumas perguntas. Aceite todos os valores padrão pressionando Enter.

Listagem 4. Executando o sphinx-quickstart
$ sphinx-quickstart 
Welcome to the Sphinx 1.0.5 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
[...]

Eu escolhi "My Project" como o nome de projeto que será referenciado em vários lugares. Você pode escolher um nome diferente.

Após executar o comando sphinx-quickstart, deve haver arquivos no diretório ativo semelhantes aos da Listagem 5.

Listagem 5. Listagem do diretório ativo
.
├── Makefile
├── _build
├── _static
├── conf.py
└── index.rst

Vamos examinar de perto cada arquivo.

  • Makefile: Desenvolvedores que já compilaram código devem estar familiarizados com esse arquivo. Caso contrário, considere-o um arquivo que contém instruções para desenvolver a saída de documentação ao usar o comando make.
  • _build: Esse é o diretório no qual os arquivos gerados serão colocados após uma saída específica ser acionada.
  • _static: Arquivos que não fazem parte do código fonte (como imagens) são colocados aqui, e depois vinculados no diretório de desenvolvimento.
  • conf.py: Esse é um arquivo Python que contém valores de configuração do Sphinx, incluindo aqueles selecionados quando sphinx-quickstart foi executado no terminal.
  • index.rst: A raiz do projeto de documentação. Isso irá conectar outros arquivos caso a documentação seja dividida em outros arquivos.

Introdução

Até agora instalamos o Sphinx adequadamente, vimos a estrutura padrão e reconhecemos um pouco da sintaxe básica. Evite começar imediatamente a escrever documentação. Falta de conhecimento sobre layout e saídas pode confundir e pode diminuir significativamente todo o seu processo.

Olhe dentro de index.rst. Há um volume significativo de informações e um pouco de sintaxe completa adicional. Para facilitar as coisas e evitar distrações, iremos incorporar um novo arquivo listando-o na seção principal.

Logo após o título principal no arquivo index.rst, há uma lista de conteúdo com uma declaração toctree. O toctree é o elemento central para reunir todos os documentos na documentação. Se outros arquivos estiverem presentes, mas não listados sob essa diretiva, esses arquivos não seriam gerados com a documentação no momento do desenvolvimento.

Queremos incluir um novo arquivo na documentação e ele irá se chamar example.rst. Ele deve ser listado no toctree, mas tenha cuidado. Há um espaçamento que precisa ser seguido para que a listagem funcione e a extensão de arquivo não é necessária (.rst , nesse caso).A Listagem 6 mostra como essa lista deve ser. Três espaços em branco precisam separar o nome do arquivo da margem esquerda, com uma linha em branco após a opção maxdepth.

Listagem 6. Exemplo de toctree no index.rst
Contents:

.. toctree::
   :maxdepth: 2

   example

Não se preocupe com as outras opções neste momento. Por ora, fique sabendo que há um arquivo de índice no qual outros arquivos separados estão listados que pode conter documentação válida, e que essa listagem segue uma certa ordem e espaçamento para funcionar.

Lembra-se do exemplo de sintaxe na Listagem 2? Copie e cole o exemplo no arquivo example.rst e salve-o. Agora estamos prontos para gerar saída.

Execute o comando make e especifique HTML como saída. Essa saída pode ser usada diretamente como um website, pois tudo já foi gerado, incluindo JavaScript e arquivos CSS. Consulte a Listagem 7.

Listagem 7. Saída do comando make html
$ make html
sphinx-build -b html -d _build/doctrees   . _build/html
Making output directory...
Running Sphinx v1.0.5
loading pickled environment... not yet created
building [html]: targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index 
writing additional files... genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.

Desenvolvimento concluído. As páginas HTML estão em _build/html.

Se estiver interessado em outras opções que o comando make oferece, veja a Listagem 8 para passar o sinalizador de ajuda para ele e ver uma descrição completa.

Listagem 8. Listando opções de make
$ make -h
Usage: make [options] [target] ...
Options:
[...]

Ficando estático

Com nossa primeira passagem na geração de HTML a partir dos dois arquivos, temos um website completamente funcional (estático).

Dentro do diretório _build, deve haver agora dois novos diretórios: doctrees e HTML. Estamos interessados no diretório HTML, que contém todos os arquivos necessários para o site de documentação. Abrir o arquivo index.html com um navegador deve revelar algo como a Figura 1.

Figura 1. Página principal em HTML estático
Página principal em HTML estático

Com tão pouca informação, Sphinx conseguiu criar muito. Temos um layout básico com algumas informações sobre a documentação do projeto, uma seção de procura, índice, avisos de copyright com nome e data, e paginação.

A parte de procura é interessante porque o Sphinx indexou todos os arquivos e, com a mágica do JavaScript, criou um site estático que pode ser pesquisado.

Lembre-se que incluímos example como um arquivo separado na documentação no toctree na Listagem 6? Você pode ver que o título principal é mostrado como um marcador principal na indexação de conteúdo, e o subtítulo, como marcadores de segundo nível. Sphinx deu conta de toda a estruturação apropriada.

Se não conseguir na primeira vez...

Após modificações adicionais, basta executar o comando make novamente para gerar os arquivos.

Todos os links apontam para os lugares certos na documentação, e títulos e subtítulos têm âncoras que permitem links diretos. Por exemplo, a seção Subject Subtitle contém uma âncora que se parece com ../example.html#subject-subtitle no navegador. Como mencionado antes, com a ferramenta não é preciso se preocupar com esses pequenos requisitos repetitivos.

A Figura 2 mostra como example.rst fica como um arquivo HTML no site estático.

Figura 2. Página de exemplo como HTML
Página de exemplo como HTML

Passando para gráfico

Parágrafos curtos e concisos, imagens e gráficos geram interesse e facilitam a leitura da documentação de um projeto. O Sphinx ajuda a manter a atenção do leitor com esses importantes elementos, com a possibilidade de incluir arquivos estáticos.

A sintaxe apropriada para incluir arquivos estáticos é fácil de lembrar. Desde que você coloque os arquivos estáticos no diretório _static que o Sphinx criou quando o layout da documentação foi criado, você deve poder referenciá-lo sem problema. Na Listagem 9, veja como essa referência deve ficar no arquivo reStructuredText. Nesse caso, eu o estou incluindo na parte inferior de example.rst.

Listagem 9. Listagem estática em example.rst
.. image:: _static/system_activity.jpg

Após a documentação ser regenerada, a imagem deve ser colocada corretamente no mesmo lugar onde indicamos o caminho para o pequeno gráfico JPEG sobre atividade do sistema. Deve ser semelhante à Figura 3.

Figura 3. Imagem de atividade do sistema
Imagem de atividade do sistema

Conclusão

Este artigo abordou os aspectos básicos para começar a usar o Sphinx, mas há muito a explorar. Sphinx pode exportar documentação em diferentes formatos, mas eles exigem quer bibliotecas e software extras sejam instalados. Alguns dos formatos que podem ser gerados são: PDF, epub, man (Páginas de Manual do UNIX) e LaTeX.

Para gráficos complexos, há um plugin para incluir gráficos Graphviz em um projeto de documentação. Uma vez, tive que criar um para o mapa de rede de um pequeno escritório, e foi bom poder ter tudo na mesma documentação sem precisar usar uma ferramenta diferente. Assim como o plugin Graphviz, há diversos plugins (também chamado de extensões) disponíveis para o Sphinx. Alguns são incluídos, como interSphinx, que permite vincular diferentes projetos do Sphinx.

Se a aparência da saída gerada não tiver agradado a você, o Sphinx inclui muitos temas que podem ser aplicados para alterar completamente a maneira como arquivos HTML renderizam a documentação. Alguns importantes projetos de software livre, como Celery e Lettuce, modificam muito a aparência de HTML alterando o CSS e estendendo os modelos. Consulte a seção Recursos para ver links para esses projetos e para a documentação que explica como estender e modificar o CSS e layout padrão.

Sphinx mudou a maneira como eu via a criação de documentação. Eu passei de desmotivado a animado quando pude documentar facilmente a maioria dos meus projetos de software livre e mais alguns internos. Use Sphinx para recuperar facilmente informações esquecidas em sua própria documentação.


Download

DescriçãoNomeTamanho
Sample Sphinx project for this articleexample_sphinx_project.zip142KB

Recursos

Aprender

Obter produtos e tecnologias

  • Avalie produtos de software IBM: a partir de downloads de teste para produtos hospedados na nuvem, é possível inovar no seu próximo projeto de desenvolvimento de software livre usando software especialmente para desenvolvedores.

Discutir

Comentários

developerWorks: Conecte-se

Los campos obligatorios están marcados con un asterisco (*).


Precisa de um ID IBM?
Esqueceu seu ID IBM?


Esqueceu sua senha?
Alterar sua senha

Ao clicar em Enviar, você concorda com os termos e condições do developerWorks.

 


A primeira vez que você entrar no developerWorks, um perfil é criado para você. Informações no seu perfil (seu nome, país / região, e nome da empresa) é apresentado ao público e vai acompanhar qualquer conteúdo que você postar, a menos que você opte por esconder o nome da empresa. Você pode atualizar sua conta IBM a qualquer momento.

Todas as informações enviadas são seguras.

Elija su nombre para mostrar



Ao se conectar ao developerWorks pela primeira vez, é criado um perfil para você e é necessário selecionar um nome de exibição. O nome de exibição acompanhará o conteúdo que você postar no developerWorks.

Escolha um nome de exibição de 3 - 31 caracteres. Seu nome de exibição deve ser exclusivo na comunidade do developerWorks e não deve ser o seu endereço de email por motivo de privacidade.

Los campos obligatorios están marcados con un asterisco (*).

(Escolha um nome de exibição de 3 - 31 caracteres.)

Ao clicar em Enviar, você concorda com os termos e condições do developerWorks.

 


Todas as informações enviadas são seguras.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=80
Zone=Software livre, Linux
ArticleID=780736
ArticleTitle=Documentação simples e sofisticada com Sphinx
publish-date=12152011