jump to navigation

2011/01/29

Posted by gsavix in como gerar documentos a partir dos programas fonte, gerador documentos, publicador documentação.
trackback

Sphinx é uma ferramenta que torna mais fácil, inteligente e bela a documentação. Escrito por Georg Brandl e traduzido por Gilberto dos Santos Alves é licenciado sob a licença BSD.

Foi criado pelo grupo Uma nova documentação Python, e tem excelentes recursos para documentar projetos Python, C/C++, JavaScript, PHP, Perl e foi planejado para adicionar suporte especial a outras linguagens também. Claro que este documento foi criado através de reStructuredText usando Sphinx!

Sphinx está sob constante desenvolvimento. As seguintes funcionalidades estão presentes e funcionam bem. Podem ser vistas “ em ação ” em docs Python:

  • Formatos de saída: HTML (incluindo Windows HTML Help), LaTeX para versões PDF impressas, páginas manual (MAN), texto plano.
  • Referência cruzada extensiva: marcas semânticas e ligações automáticas para: funções, classes, citações, glossários e outros tipos de fragmentos de informações.
  • Estrutura hierárquica: Fácil definição da estrutura (árvore) do documento, com ligações dinâmicas para páginas antecessoras e sucessoras (pais / filhos)
  • Índices automáticos: Índices Gerais bem como módule índice
  • Manejo de código: Enfâse automática de sintaxe, através de cores utilizando Pygments.
  • Extensões: Automação no teste de código snippets, inclusão de docstrings de módulos Python (API docs), e mais …

Sphinx usa reStructuredText como sua linguagem de marcação, e muito das suas facilidades vem da flexibilidade e da vanguarda em passar e traduzir reStructuredText através da suite Docutils.

Documentação

Primeiros passos com Sphinx
visão geral de tarefas básicas

Sumário
para visão geral completa

Página Busca
pesquisa na documentação

Índice Geral
todas funções, classes e termos

Você também pode fazer download de documentação Sphinx em formato PDF: Versão PDF Gerada a partir do LaTeX que o Sphinx produz, ou Versão PDF gerada pelo rst2pdf.

Exemplos

Ligações para documentação gerada com Sphinx podem ser encontradas no página Projetos usando Sphinx.

Para exemplos de como fontes Sphinx aparentam, use “Exibir Fonte” ligações que estão todas as páginas, a partir desta página de Boas Vindas.

Você também pode se interessar, por esse agradável tutorial que apresenta como criar documentação personalizada usando Sphinx, que foi escrito pelos desenvolvedores de matplotlib.

Existe uma tradução em em Japonês desta documentação, agradecimentos a Yoshiki Shibukawa.

Obter Sphinx

Sphinx está disponível como easy-install ou como pacote de Python Package Index.

O código pode ser encontrado no repositório Mercurial, em http://bitbucket.org/birkenfeld/sphinx/.

Anúncios

Comentários»

No comments yet — be the first.

Deixe um comentário

Faça o login usando um destes métodos para comentar:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair / Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair / Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair / Alterar )

Foto do Google+

Você está comentando utilizando sua conta Google+. Sair / Alterar )

Conectando a %s

%d blogueiros gostam disto: