Primeiros passos¶

Sphinx é um gerador de documentação ou uma ferramenta que traduz um conjunto de arquivos fonte de texto simples em vários formatos de saída, produzindo automaticamente referências cruzadas, índices, etc. Ou seja, se você tiver um diretório contendo um monte de documentos reStructuredText ou Markdown, o Sphinx pode gerar uma série de arquivos HTML, um arquivo PDF (via LaTeX), páginas man e muito mais.

O Sphinx se concentra na documentação, em particular na documentação manuscrita; no entanto, o Sphinx também pode ser usado para gerar blogs, páginas iniciais e até livros. Muito do poder do Sphinx vem da riqueza de seu formato de marcação de texto simples padrão, reStructuredText, junto com seus recursos de extensibilidade significativos.

O objetivo deste documento é dar a você uma ideia rápida do que é o Sphinx e como você pode usá-lo. Quando terminar aqui, você pode conferir o guia de instalação seguido pela introdução do formato de marcação padrão usado pelo Sphinx, reStructuredText.

Para obter uma excelente “introdução” à escrita de documentos em geral – os porquês e comos, consulte também Write the docs, escrito por Eric Holscher.

Configurando fontes de documentação¶

O diretório raiz de uma coleção Sphinx de fontes de documentos de texto simples é chamado de diretório fonte. Este diretório também contém o arquivo de configuração conf.py do Sphinx, onde você pode configurar todos os aspectos de como o Sphinx lê suas fontes e constrói sua documentação. [1]

O Sphinx vem com um script chamado sphinx-quickstart que configura um diretório fonte e cria um conf.py padrão com os valores de configuração mais úteis de algumas perguntas que ele faz. Para usar isso, execute:

$ sphinx-quickstart

Definindo a estrutura do documento¶

Vamos presumir que executou sphinx-quickstart. Isso criou um diretório fonte com conf.py e um documento raiz index.rst. A função principal do documento raiz é servir de página de boas-vindas, bem como conter a documentação raiz da estrutura “sumário” ou (toctree). Isso é um dos princípios que Sphinx usa para adicionar reStructuredText para conectar múltiplos arquivos em uma hierarquia simples de documentos.

Diretivas do reStructuredText

toctree é uma diretiva do reStructuredText, uma peça muito versátil de marcação. Diretivas podem conter argumentos, opções e conteúdos.

Argumentos são fornecidos diretamente após duplo dois pontos seguidos do nome da diretiva. Cada diretiva decide se existem e quantos são os argumentos.

Opções são fornecidas após os argumentos, na forma de “lista de campos”. Como em maxdepth que é uma opção da diretiva toctree.

Conteúdo seguem as opções ou os argumentos após uma linha em branco. Cada diretiva decide se permite conteúdo e como tratá-lo.

Um pegadinha comum com diretivas é que a primeira linha do conteúdo precisa estar alinhada (com espaços) ao mesmo nível das opções.

A diretiva toctree inicialmente está vazia e se parece com isso:

.. toctree::
   :maxdepth: 2

Você adiciona documentos listando-os no conteúdo da diretiva:

.. toctree::
   :maxdepth: 2

   usage/installation
   usage/quickstart
   ...

É exatamente assim que a toctree desta documentação parece. Os documentos a incluir são fornecidos como nome do documento, o que, em suma, significa que você deixa a extensão do nome do arquivo e usa barras (/) como separadores de diretório.

Ver também

Adicionando conteúdo¶

Nos arquivos fonte do Sphinx, você pode usar a maioria dos recursos do padrão reStructuredText. Há também vários recursos adicionados pelo Sphinx. Por exemplo, você pode adicionar referências de arquivo cruzado de maneira portátil (que funciona para todos os tipos de saída) usando o papel ref.

Por exemplo, se você estiver visualizando a versão HTML, poderá olhar o código-fonte deste documento – use o link “Exibir Fonte” na barra lateral.

Ver também

reStructuredText para uma introdução mais aprofundada ao reStructuredText, incluindo marcação adicionada pelo Sphinx.

Construindo¶

Agora que você adicionou alguns arquivos e conteúdo, vamos fazer uma primeira construção dos documentos. Uma construção é iniciada com o programa sphinx-build:

$ sphinx-build -M html sourcedir outputdir

onde sourcedir é o diretório fonte e outputdir é o diretório no qual deseja-se colocar a documentação construída. A opção -M seleciona um construtor, nesse exemplo Sphinx vai construir arquivos HTML.

Ver também

Consulte a página man do sphinx-build para todas as opções as quais o sphinx-build oferece suporte.

Você também pode construir uma versão live da documentação que pode ser visualizada no navegador. Ele detectará alterações e recarregará a página sempre que você fizer edições. Para fazer isso, use sphinx-autobuild para executar o comando a seguir:

$ sphinx-autobuild source-dir output-dir

No entanto, o script sphinx-quickstart cria um Makefile e um make.bat que tornam a vida ainda mais fácil para você. Estes podem ser executados executando make com o nome do construtor. Por exemplo.

$ make html

Isto irá construir documentos HTML no diretório de construção que você escolheu. Execute make sem um argumento para ver quais alvos estão disponíveis.

Como gerar documentos em PDF?

make latexpdf executa o construtor LaTeX e já chama a cadeia de ferramentas pdfTeX. Para executar.

Documentando objetos¶

Um dos principais objetivos do Sphinx é a fácil documentação de objetos (em senso geral) de qualquer domínio. Um domínio é uma coleção de tipos de objetos comuns entre si, com marcação completa para criar descrição referencial desses objetos.

O domínio mais proeminente é o domínio Python. Por exemplo, para documentar a função interna do Python enumerate(), você adicionaria isso a um dos seus arquivos de origem.

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

   Return an iterator that yields tuples of an index and an item of the
   *sequence*. (And so on.)

Isso é renderizado como:

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

O argumento da diretiva é a assinatura do objeto a ser descrito, o conteúdo de sua documentação. Múltiplas assinaturas podem ser dadas, cada uma em sua própria linha.

O domínio Python também é o domínio padrão, portanto, você não precisa prefixar a marcação com o nome do domínio.

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

   ...

isso faz a mesma coisa para o domínio que for o escolhido como padrão.

Existem várias outras diretivas para documentar outros tipos de objetos Python, por exemplo py:class ou py:method. Há também uma referência cruzada role para cada um desses tipos de objeto. Esta marcação criará um link para a documentação do enumerate().

The :py:func:`enumerate` function can be used for ...

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

Relembrando que, py: pode ser omitido no domínio Python que é o padrão. Não importa em qual arquivo está a documentação para enumerate(); Sphinx irá encontrar e criar um link para isso.

Cada domínio tem regras especiais para como a assinatura deve parecer e torna a saída formatada com um visual agradável, além disso pode adicionar funcionalidades específicas como links para tipos de parâmetros em domínios C/C++.

Ver também

Veja Domínios para todos os domínios disponíveis e suas diretivas e seus papéis.

Configuração básica¶

Já foi mencionado que o arquivo conf.py controla como o Sphinx processa seus documentos. Nesse arquivo que é interpretado como um arquivo fonte Python, podem ser assinalados valores. Para usuários avançados: uma vez que é executado pelo Sphinx, podem ser feitas tarefas não triviais como ampliar sys.path ou importar um módulo para encontrar a versão da documentação.

Os valores do config que provavelmente serão modificados já estão postos no arquivo conf.py pelo programa sphinx-quickstart e inicialmente marcados como comentário (em Python a sintaxe # indica comentário para o resto da linha). Para modificar um valor padrão, remove o jogo da velha e modifique o valor desejado. Para configurar um valor do config que não está declarado, apenas adicione uma linha com a opção e assinalamento desejados.

Lembre-se de que o arquivo usa a sintaxe do Python para strings, números, listas e assim por diante. O arquivo é salvo em UTF-8 por padrão, conforme indicado pela declaração de codificação na primeira linha.

Ver também

Configuração para documentação de todos os valores de configuração disponíveis.

Autodoc¶

Ao documentar o código Python, é comum colocar muita documentação nos arquivos de origem, nas strings de documentação. O Sphinx oferece suporte à inclusão de docstrings de seus módulos com uma extensão (uma extensão é um módulo Python que fornece recursos adicionais para projetos Sphinx) chamado autodoc.

Ver também

sphinx.ext.autodoc para descrição completa das funcionalidades do autodoc.

Intersphinx¶

Muitos documentos do Sphinx, incluindo a documentação do Python, são publicados na Internet. Quando você quiser criar links para esses documentos a partir de sua documentação, você pode fazê-lo com sphinx.ext.intersphinx.

Para usar o intersphinx, é necessário ativá-lo no conf.py adicionando a string 'sphinx.ext.intersphinx' na lista extensions e definir o valor de configuração intersphinx_mapping.

Por exemplo, para adicionar um link para io.open() no manual de bibliotecas do Python, é necessário usar intersphinx_mapping:

intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}

E agora, você pode escrever uma referência cruzada como :py:func:`io.open. Qualquer referência cruzada que não tenha um alvo correspondente no conjunto de documentações atual será pesquisada nos conjuntos de documentação configurados em intersphinx_mapping (isso requer acesso ao URL para fazer o download da lista de alvos válidos). O Intersphinx também funciona para outros papéis do domínio, incluindo :ref:, no entanto, ele não funciona para :doc:, já que isso não é um papel de domínio.

Ver também

sphinx.ext.intersphinx para descrição completa das funcionalidades do intersphinx.

Mais tópicos para cobrir¶

Notas de rodapé