Documentação narrativa no Sphinx¶
Estruturando sua documentação em múltiplas páginas¶
O arquivo index.rst criado por sphinx-quickstart é o documento raiz, cuja principal função é servir como uma página de boas-vindas e conter a raiz da “árvore do tabela de conteúdo” (ou toctree). O Sphinx permite montar um projeto a partir de diferentes arquivos, o que é útil quando o projeto cresce.
Como exemplo, crie um novo arquivo docs/source/usage.rst (ao lado de index.rst) com este conteúdo:
Usage
=====
Installation
------------
To use Lumache, first install it using pip:
.. code-block:: console
(.venv) $ pip install lumache
Este novo arquivo contém dois cabeçalhos de seção, texto de parágrafo normal e uma diretiva code-block que renderiza um bloco de conteúdo como código-fonte, com realce de sintaxe apropriado (neste caso, texto genérico console).
A estrutura do documento é determinada pela sucessão de estilos de cabeçalho, o que significa que, ao usar --- para a seção “Installation” depois de === para a seção “Usage”, você declarou “Installation” como uma subseção de “Usage”.
Para completar o processo, adicione uma diretiva toctree no final de index.rst incluindo o documento que você acabou de criar, como segue:
Contents
--------
.. toctree::
usage
Este passo insere esse documento na raiz do toctree, então agora ele pertence à estrutura do seu projeto, que até agora está assim:
index
└── usage
Se você construir a documentação HTML executando make html, você verá que o toctree é renderizado como uma lista de hiperlinks, e isso permite que você navegue para a nova página que acabou de criar. Bem organizado!
Aviso
Documentos fora de um toctree resultarão em mensagens AVISO: o documento não está incluído em nenhum toctree durante o processo de construção e ficarão inacessíveis para os usuários.
Adicionando referências cruzadas¶
Um recurso poderoso do Sphinx é a capacidade de adicionar referências cruzadas para partes específicas da documentação: um documento, uma seção, uma figura, um objeto código, etc. Este tutorial está cheio deles!
Para adicionar uma referência cruzada, escreva esta frase logo após o parágrafo de introdução em index.rst:
Check out the :doc:`usage` section for further information.
O papel doc que você usou automaticamente faz referência a um documento específico no projeto, neste caso o usage.rst que você criou anteriormente.
Alternativamente, você também pode adicionar uma referência cruzada a uma parte arbitrária do projeto. Para isso, você precisa usar o papel ref, e adicionar um rótulo explícito que atue como um alvo.
Por exemplo, para fazer referência à subseção “Installation”, adicione um rótulo logo antes do título da seguinte forma:
Usage
=====
.. _installation:
Installation
------------
...
E faça com que a frase que você adicionou em index.rst fique assim:
Check out the :doc:`usage` section for further information, including how to
:ref:`install <installation>` the project.
Observe um truque aqui: a parte install especifica como será a aparência do link (queremos que seja uma palavra específica, para que a frase faça sentido), enquanto a parte <installation> refere-se ao rótulo real ao qual queremos adicionar uma referência cruzada. Se você não incluir um título explícito, portanto usando :ref:`installation`, o título da seção será usado (neste caso, Installation). Ambas os papéis :doc: e :ref: serão renderizadas como hiperlinks na documentação HTML.
E quanto a documentar objetos código no Sphinx? Continue lendo!