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.
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 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.
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.
Veja 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
where sourcedir is the source directory, and outputdir is the
directory in which you want to place the built documentation.
The -M option selects a builder; in this example
Sphinx will build HTML files.
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 construçã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++.
See Domínios for all the available domains
and their directives/roles.
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.
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 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.
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.
Veja 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 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 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.
Veja sphinx.ext.intersphinx para descrição completa das funcionalidades do intersphinx.
Mais tópicos para cobrir¶
Arquivos estáticos
Usando extensões
Notas de Rodapé