Primeiros passos para documentar seu projeto usando Sphinx

Construindo sua documentação HTML

O arquivo index.rst que o sphinx-quickstart criou já tem algum conteúdo e é renderizado como a primeira página da sua documentação HTML. Está escrito em reStructuredText, uma linguagem de marcação poderosa.

Modifique o arquivo da seguinte forma:

docs/source/index.rst
Welcome to Lumache's documentation!
===================================

**Lumache** (/lu'make/) is a Python library for cooks and food lovers that
creates recipes mixing random ingredients.  It pulls data from the `Open Food
Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and
*intuitive* API.

.. note::

   This project is under active development.

Isso mostra vários recursos da sintaxe reStructuredText, incluindo:

  • um cabeçalho de seção usando === para o sublinhado,

  • dois exemplos de Marcação Inline: **ênfase forte** (normalmente em negrito) e *ênfase* (normalmente em itálico),

  • um link externo em linha,

  • e uma nota advertência (uma das diretivas disponíveis)

Agora, para renderizá-la com o novo conteúdo, você pode usar o comando sphinx-build como antes, ou aproveitar o script de conveniência da seguinte forma:

(.venv) $ cd docs
(.venv) $ make html

Após executar este comando, você verá que index.html reflete as novas alterações!

Construindo sua documentação em outros formatos

Sphinx oferece suporte a uma variedade de formatos além de HTML, incluindo PDF, EPUB e mais. Por exemplo, para construir sua documentação no formato EPUB, execute este comando no diretório docs:

(.venv) $ make epub

Depois disso, você verá os arquivos correspondentes ao e-book em docs/build/epub/. Você pode abrir Lumache.epub com um visualizador de e-book compatível com EPUB, como Calibre ou visualizar index.xhtml em um navegador web.

Nota

Para exibir rapidamente uma lista completa de possíveis formatos de saída, além de alguns comandos extras úteis, você pode executar make help.

Cada formato de saída possui algumas opções de configuração específicas que você pode ajustar, incluindo EPUB. Por exemplo, o valor padrão de epub_show_urls é inline, o que significa que, por padrão, as URLs são mostradas logo após o link correspondente, entre parênteses. Você pode mudar esse comportamento adicionando o seguinte código no final do seu conf.py:

# EPUB options
epub_show_urls = 'footnote'

Com este valor de configuração, e após executar novamente make epub, você notará que as URLs aparecem agora como notas de rodapé, o que evita sobrecarregar o texto. Legal! Continue lendo para explorar outras maneiras de personalizar o Sphinx.

Nota

A geração de um PDF usando o Sphinx pode ser feita executando make latexpdf, desde que o sistema tenha uma instalação LaTeX funcional, conforme explicado na documentação de sphinx.builders.latex.LaTeXBuilder. Embora isso seja perfeitamente viável, tais instalações costumam ser grandes e, em geral, o LaTeX requer configuração cuidadosa em alguns casos, portanto a geração de PDF está fora do escopo deste tutorial.