jump to navigation

Primeiros passos com o Sphinx 2011/02/01

Posted by gsavix in ciência colaborativa, colaboração na aquisição conhecimento, como gerar documentos a partir dos programas fonte, como publicar na internet gratuitamente, Computadores, Conhecimento para receber ou transferir tecnologia, Doc, Memorando, metodologia para receber ou transferir conhecimento, publicação jornal internet, publicador documentação, sociologia do conhecimento, Soft.
Tags: , , , , , ,
trackback

Primeiros passos com Sphinx

Esse documento é para permitir uma visão como um tutorial, nas tarefas mais comuns no uso do Sphinx.

A seta verde designa “mais informações”, através de ligações para seções avançadas descrevendo a tarefa.

Configurando fontes da documentação

O diretório ou pasta raiz, da coleção tem o nome de source directory. Nele também está o arquivo de configuração Sphinx conf.py, onde você pode configurar todos os aspectos, sobre como o Sphinx faz a leitura dos seus fontes e constrói sua documentação. [1]

O Sphinx vem com um script chamado sphinx-quickstart que configura on diretório ou pasta fonte, além de criar um arquivo padrão chamado conf.py com as opções mais comuns, a partir de poucas perguntas feitas para você. Apenas execute:

$ sphinx-quickstart

e responda as perguntas. (Certifique-se de responder yes para a extensão “autodoc”.)

Definindo a estrutura do Documento

Vamos assumir que você já executou sphinx-quickstart. Foi criado um diretório ou pasta contendo o arquivo conf.py e um arquivo com documento mestre index.rst (se você aceitou os padrões). A função principal do master document é servir como página de boas vindas, e conter a raiz da TOC (tabela de Conteúdos) ou (toctree). Isto é uma das principais coisas que o Sphinx adiciona ao reStructuredText, (RST) uma maneira de conectar múltiplos arquivos em uma hierarquia única hierarquia de documentos.

Diretivas reStructuredText

toctree é uma directiva de reStructuredText, uma peça versátil de markup. Diretivas podem conter argumentos, opções e conteúdo.

Argumentos são fornecidos diretamento após (dois pontos) seguidos pelo name da diretiva. Cada diretiva decide quando e quantos argumentos pode ter.

Opções são fornecidas após os argumentos, na forma de “lista de campos”. O maxdepth é uma opção para a diretiva toctree.

Conteúdo seguindo Argumentos ou Opções após uma linha em branco. Cada diretiva decide quando pode haver conteúdo e o que fazer com ele.

Uma pegadinha com diretivas é que a primeira linha do conteúdo precisa estar “indentada” (ou alinhada) à mesma coluna onde a opção está.

A diretiva toctree inicialmente está vazia, e parece com:

.. toctree::
   :maxdepth: 2

Você adiciona documentos na lista, preenchendo o Conteúdo da diretiva:

.. toctree::
   :maxdepth: 2

   intro
   tutorial
   ...

É exatamente assim que toctree para documentação parece. Os documentos para incluir são colocados como nome do documento, os quais de maneira resumida, significa que você não quis informar as extensão do arquivo, e vai utilizar a barra como separador de diretórios ou pastas.

more Leia mais sobre Diretiva toctree.

Você pode criar os arquivos que você inseriu em toctree e adicionar conteúdo, e os títulos deles serão inseridos até o nível especificado por “maxdepth” da diretiva toctree. Agora, o Sphinx sabe a ordem e a hierarquia dos documentos, os quais podem conter diretivas toctree neles mesmos, o que significa que você pode especificar várias hierarquias subordinadas se necessário.

Adicionando conteúdo

Em arquivos fonte Sphinx, você pode usar muitas funcionalidades padrão de (RST) reStructuredText. Além destas, existem outros adicionadas pelo Sphinx. Por exemplo, você pode adicionar referências cruzadas entre arquivos, de uma maneira portável (pois funcionam para todos os tipos de saída), através de ref role.

Por exemplo, se você está vendo a versão HTML, você pode dar uma olhada na fonte do documento – usando o link “Exibir Código Fonte” na barra lateral.

more Veja reStructuredText Princípios para maiores detalhes ao reStructuredText e marcas_sphinx para uma lista completa de marcações adicionadas pelo Sphinx.

Rodando o build

Agora que você adicionou alguns arquivos e conteúdos, vamos fazer nosso primeiro “build” (construir) dos documentos. A construção é iniciada com o programa sphinx-build, o qual é chamado como:

$ sphinx-build -b html diretório_fonte diretório_construído

onde diretório-fonte é onde estão seus arquivos reStructuredText e o diretório_construído é o diretório ou pasta onde você deseja colocar a documentação construída. A opção -b seleciona o construtor; nesse exemplo Sphinx irá construir arquivos HTML.

mais informações Veja chamada para todas as opções que o programa sphinx-build permite.

Contudo, o script sphinx-quickstart cria um arquivo a Makefile e um arquivo make.bat que tornam a vida mais fácil para você, pois para criar a documentação você só precisa escrever:

$ make html

para construir docs HTML no diretório que você escolheu. Execute make sem argumento para ver quais possibilidades estão disponíveis.

Documentando objetos

Um dos principais objetivos do Sphinxs, é a documentação fácil de objetos objetos (em termos gerais) em qualquer domínio. Um domínio é uma coleção de tipos de objetos, que juntos com marcas, criam e referenciam descrições a estes objetos.

O domínio mais importante é o Python. Por ex.: a função interna enumerate(), você pode adicionar isto aos seus arquivos fonte:

.. py:function:: enumerate(sequence[, start=0])

   Retorna um iterator que aponta tuples de um índice e um item de
   *sequência*. (E assim sucessivamente.)

Isso é renderizado (deduzido) como:

enumerate(sequence[, start=0])
Retorna um iterator que aponta tuples de um índice e um item de
sequência. (E assim sucessivamente.)

O argumento da diretiva é a assinatura do objeto que você descreve, o conteúdo é a documentação dele. Múltiplas assinaturas podem ser dadas, cada uma em sua linha.

O domínio Python também ocorre como domínio padrão, portanto você não precisa colocar o prefixo de marcação no nome do domínio:

.. function:: enumerate(sequence[, start=0])

   ...

faz o mesmo se você manter a configuração padrão para domínio.

Existem muitos outras diretivas para documentar outros tipos de objetos Python, por exemplo: py:class or py:method. Existe também uma definição de referência cruzada role para cada um desses objetos. Essa marcação irá criar uma ligação em enumerate():

A função :py:func:`enumerate` pode ser usada para ...

E aqui a prova: Um link para enumerate().

Recapitulando, o prefixo py: pode ser omitido para o domínio Python pois é o padrão. Não importa qual arquivo contem a documentação para enumerate(); O Sphinx irá encontrar e criar um link para este arquivo.

Cada domínio terá regras especiais para como são as assinaturas e fazer a saída formatada aparecer bem formatada ou adicionar funcionalidades como ligação para tipos de parâmetros, ex. em domínios C/C++.

more Veja domínios para todas as diretivas e roles disponíveis.

Configurações básicas

Anteriormente mencionamos que o arquivo conf.py controla como o Sphinx processa seus documentos. Quando este arquivo, é executado como um fonte Python, você assinala cada um dos valores, nele existentes. Para usuários avançados: deste que executado pelo Sphinx, você pode executar tarefas não triviais, a partir deste arquivo, como extensão sys.path our importar um módulo para encontrar a versão que você está documentando. Os valores configurados que você provavelmente deseja modificar, já foram gravados no arquivo conf.py pelo sphinx-quickstart e inicialmente definidos como comentários com a sintaxe padrão Python # torna comentário o resto da linha. Para modificar o valor padrão, remova o # e modifique o conteúdo da variável para o valor desejado. Para personalizar um valor que não foi automaticamente adicionado pelo programa sphinx-quickstart, apenas faça um assinalamente adicional.

Tenha em mente que o arquivo utiliza sintaxe do Python para strings, números, listas e assim por diante. O arquivo é salvo em unicode UTF-8 por padrão como indicado pela declaração de codificação da primeira linha. Se você usar caracteres não ASCII em qualquer valor de string, você precisa utilizar Python Unicode (como project = u'Exposé').

mais informações Veja Arquivo de configuração do build para documentação de todos os valores disponíveis.

Autodoc

Quando documentar código Python, é comum colocar um monte de documentação nos arquivos fonte, em strings de documentação. Sphinx suporta a inclusão de docstrings a partir de seus módulos com uma extensão (uma extensão é um módulo Python que provê funcionalidades adicionais para os projetos Sphinx) chamada “autodoc”.

Para utilizar autodoc, você precisa ativar esta extensão no arquivo conf.py colocando a string 'sphinx.ext.autodoc' na lista assinalada contendo extensions. Então você terá mais diretivas à sua disposição.

Por exemplo, para documentar a função io.open(), lendo sua assinatura e a docstring do arquivo fonte, você escreverá:

.. autofunction:: io.open

Você também pode documentar todas as classes ou mesmo todos os módulos, automáticamente usando as opções de membros para diretivas auto, ficando assim:

.. automodule:: io
   :members:

autodoc precisa importar seus módulos para extrair as docstrings. Todavia, você precisar adicionar o caminho correto para sys.path no seu arquivo conf.py.

mais informações Veja sphinx.ext.autodoc para descrição completa para funcionalidades autodoc.

Mais tópicos serão cobertos

  • Outras extensões (math, intersphinx, viewcode, doctest)
  • Arquivos Státicos
  • Selecionando um tema
  • Modelos (Templating)
  • Usando extensions
  • Escrevendo extensões

Notas de Rodapé

[1] Essa é a formatação usual. Contudo, o arquivo conf.py pode também estar em outro diretório ou pasta, o diretório de configuração. Veja Chamando sphinx-build.
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: