Iniciando

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 /usage/reestruturedtext/index ou Markdown, o Sphinx pode gerar uma série de arquivos HTML, um arquivo PDF (via LaTeX), páginas de manual e muito mais.

Sphinx focuses on documentation, in particular handwritten documentation, however, Sphinx can also be used to generate blogs, homepages and even books. Much of Sphinx’s power comes from the richness of its default plain-text markup format, reStructuredText, along with its significant extensibility capabilities.

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 verificar o guia de instalação seguido pela introdução do formato de marcação padrão usado pelo Sphinx, reStucturedText.

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 de origem 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 estrutura do documento

Vamos assumir que foi executado sphinx-quickstart. Isso criou um diretório fonte com conf.py e um documento mestre index.rst. A função principal do documento mestre é 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.

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

.. toctree::
   :maxdepth: 2

Você adiciona documentos listando-os no content 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 document names, o que, em suma, significa que você deixa a extensão do nome do arquivo e usa barras (/) como separadores de diretório.

mais informações Ler mais sobre diretiva toctree.

Agora você pode criar os arquivos que você listou no toctree e adicionar conteúdo, e seus títulos de seção serão inseridos (até o nível maxdepth) no local onde a diretiva toctree é colocada. Além disso, o Sphinx agora sabe sobre a ordem e a hierarquia dos seus documentos. (Eles podem conter as diretivas toctree, o que significa que você pode criar hierarquias profundamente aninhadas, se necessário.)

Adicionando conteúdo

Nos arquivos de origem 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 a função 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.

Por fazer

Atualize o link abaixo quando adicionarmos novos guias sobre eles.

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

Executando a montagem

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

$ sphinx-build -b html sourcedir builddir

onde diretório-fonte é o source directory e diretório-montagem é o diretório no qual será criada a documentação gerada. a opção -b seleciona o construtor, nesse exemplo serão gerados arquivos HTML.

mais informações Consulte o sphinx-build man page para todas as opções que o sphinx-build suporta.

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 compilação que você escolheu. Execute make sem um argumento para ver quais alvos estão disponíveis.

Como gerar documentos PDF?

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

Por fazer

Mova toda esta seção em um guia sobre reST ou diretivas

Documentando objetos

Um dos principais objetivos do Sphinx é a fácil documentação de objetos (em senso geral) de qualquer domain. 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 é signature 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++.

mais informações Veja Domains para todos os domínios disponíveis e suas diretivas/funções.

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.

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

Por fazer

Mova este documento inteiro para uma seção diferente

Autodoc

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

Para usar o autodoc, você precisa ativá-lo em conf.py colocando a string 'sphinx.ext.autodoc' na lista atribuída ao valor da configuração extensions:

extensions = ['sphinx.ext.autodoc']

Então, você tem algumas diretivas adicionais à sua disposição. Por exemplo, para documentar a função io.open(), lendo sua assinatura e docstring do arquivo fonte, você escreveria isto:

.. autofunction:: io.open

Também podem ser documentadas automaticamente, todas classes ou mesmo módulos, usando opções para diretivas automáticas como:

.. automodule:: io
   :members:

autodoc precisa importar seus módulos para extrair as docstrings. Portanto, você deve adicionar o path apropriado para sys.path no seu conf.py.

Aviso

autodoc importa módulos para documentar. Se algum módulo tiver efeitos na importação, serão executados por autodoc quando sphinx-build for executado.

Se os scripts do seu documento, (diferentemente de módulos de biblioteca), certificar-se que suas rotinas main estejam protegidas por um if __name__ == '__main__' condição.

mais informações Ver sphinx.ext.autodoc para descrição completa das funcionalidades do autodoc.

Por fazer

Mover este documento para outra seção

Intersphinx

Muitos documentos do Sphinx, incluindo o Python documentation, 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 intersphinx, será necessário ativar no conf.py adicionando a string 'sphinx.ext.intersphinx' na lista extensions e configurar o valor intersphinx_mapping

Por exemplo, para link para io.open() no manual para biblioteca 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 destino 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 destinos válidos). O Intersphinx também funciona para outras funções do domain, incluindo :ref:, no entanto, ele não funciona para :doc:, já que isso não é uma função de domínio.

mais informações Ver sphinx.ext.intersphinx para descrição completa das funcionalidades do intersphinx.

Mais tópicos para cobrir

Notas de Rodapé

1

Este é o layout usual. No entanto, conf.py também pode viver em outro diretório, o configuration directory. Consulte o sphinx-build man page para obter mais informações.