Aproveite ao máximo os documentos do seu projeto - use o Sphinx para gerar uma documentação HTML atraente e abrangente.

Sphinx é uma das ferramentas mais populares para gerar documentação. Em toda a comunidade Python, os desenvolvedores usam esse software gratuito e de código aberto. Ele pode extrair texto diretamente de seu código ou arquivos markdown e usá-lo para gerar documentação em vários formatos, como texto simples, HTML, PDF e EPUB.

Configurando a Esfinge

Antes de configurar o Sphinx, veja o que ele faz e alguns de seus principais recursos.

O que é a Esfinge e o que ela faz?

Como mencionado, o Sphinx é um gerador de documentação. Por padrão, ele usa a linguagem de marcação reStructuredText (RST), mas por meio de extensões de terceiros, também pode use Markdown, a popular linguagem de marcação de texto simples. Em seguida, ele converte esses arquivos RST ou markdown em HTML, PDF, páginas de manual ou outros formatos de sua preferência.

Alguns dos recursos que o Sphinx inclui são:

  • Capacidade de gerar documentação a partir do código.
    • instagram viewer
  • Capacidade de fazer referência cruzada a diferentes páginas de documentos usando links automáticos para funções, classes, citações e termos do glossário.
  • Destaque de sintaxe para blocos de código.
  • Suporte para temas que podem alterar a aparência dos documentos.
  • Fácil definição da árvore de documentos através de um sumário.
  • Capacidade de integração com extensões de terceiros para adicionar mais funcionalidade aos documentos, como testar trechos de código.

Instalando o Sphinx

Antes de instalar o Sphinx, certifique-se de ter Python 3 instalado em seu ambiente de desenvolvimento. Você pode usar o gerenciador de pacotes pip para instalar o Sphinx executando o seguinte comando em seu terminal:

pip instalar esfinge

Isso fará o download e instalará o Sphinx e suas dependências.

Após a instalação, execute o seguinte no prompt de comando.

sphinx-build --version

Se tudo funcionou bem, você deve ver o número da versão do pacote Sphinx que acabou de instalar.

Criando um novo projeto Sphinx

Depois de instalar o Sphinx, navegue até o diretório de trabalho e execute o comando sphinx-quickstart para criar um novo projeto Sphinx.

sphinx-quickstart

Este comando solicitará que você responda a uma série de perguntas sobre como configurar seu projeto Sphinx. Você pode especificar o nome do projeto e usar as opções padrão para as outras questões. No futuro, você pode querer personalizar as respostas com base em seu projeto.

Se você listar o conteúdo do seu diretório, verá que este comando cria alguns arquivos para você. O conf.py contém os valores de configuração e o index.rst serve como a página de boas-vindas da sua documentação. O diretório de compilação hospedará a documentação gerada e o Sphinx usará um Makefile (make.bat no Windows) para compilar a documentação.

Escrevendo documentação usando Sphinx

O arquivo index.rst na raiz do seu diretório é a página inicial do seu aplicativo. Então, abra-o com um editor de texto como o VS Code—ou qualquer outro bom editor de código gratuito- para editá-lo.

Você pode alterar o index.rst como achar melhor, mas uma coisa que ele deve ter é pelo menos a diretiva root toctree (árvore de conteúdo). Isso é essencial, pois conecta vários arquivos a uma única hierarquia de documentos.

Para adicionar documentação ao arquivo index.rst, você pode usar a marcação RST.

Como exemplo, considere um arquivo index.rst para o módulo math_utils. Esse arquivo pode incluir uma breve visão geral da finalidade do módulo e um sumário com links para outras páginas da documentação.

Bem-vindo ao Math Utils
.. toctree::
 :profundidade máxima: 2


Começando


Para usar este módulo, você precisará do seguinte:


*Python instalado.


* Um editor de texto


Utilitários de matemática


O módulo `math-utils` fornece funções matemáticas básicas como adição e
subtração.

Você pode adicionar mais arquivos .rst conforme necessário. Por exemplo, você pode criar um guia de contribuição em um arquivo denominado contribuindo.rst contendo as seguintes diretrizes de contribuição.

Guia de contribuição
Congratulamo-nos com contribuições para o nosso projeto! Aqui estão algumas orientações para
contribuindo:


- Fork do projeto no GitHub.
- Faça suas alterações em uma nova ramificação.
- Escreva testes para garantir que suas alterações funcionem corretamente.
- Envie um pull request com suas alterações.
- Faça as alterações solicitadas.
Obrigado por contribuir!

Você pode vincular esse arquivo a partir de index.rst adicionando uma nova seção à diretiva toctree:

.. toctree::
 :profundidade máxima: 2
 :caption: Índice

 contribuindo

Isso cria um novo item chamado contribuindo no sumário que leva o usuário à página de contribuição quando clicado.

Depois de escrever a documentação, o próximo passo é criá-la. Aqui, construir a documentação significa gerar páginas HTML, manuais ou PDF a partir dos arquivos RST.

Construindo a Documentação

Para construir a documentação usando o Sphinx, você precisará executar o comando make html na raiz da sua pasta onde o makefile está localizado.

fazer html

Você deve ver os arquivos HTML na pasta de compilação. Se houver erros durante a compilação, o Sphinx informará você no terminal.

Para visualizar a documentação, abra o arquivo index.html em seu navegador:

Você deve ser capaz de navegar até o guia de contribuição a partir do sumário.

Personalizando a Documentação

No momento, a documentação tem alguns estilos básicos. Se você quiser personalizá-lo, talvez adicionando as cores da sua marca, ou mesmo adicionando um modo escuro, você pode instalar e usar outros temas embutidos ou crie seu próprio tema personalizado.

Para demonstrar, tente mudar o tema para o chamado natureza:

  1. Abra o arquivo de configuração Sphinx conf.py no diretório do projeto Sphinx.
  2. Procure a linha que define a opção html_theme e mude para nature
  3. Salve o arquivo de configuração e reconstrua a documentação para ver suas alterações.

É assim que a página inicial da documentação deve ser.

Se você não quiser usar os temas integrados, sempre poderá usar um tema Sphinx de terceiros em vez de.

Documentando seu código usando Docstrings

O Sphinx gera sua documentação Python a partir do texto que você escreve em arquivos RST. Embora isso seja suficiente em alguns casos, você também pode usar docstrings em seu código no nível do módulo.

Docstrings vivem diretamente dentro dos arquivos de origem do seu projeto. Eles permitem que você descreva o que o código faz, forneça exemplos e até mesmo crie testes para esses exemplos. Depois de escrever docstrings, você pode gerar documentação a partir delas usando o Sphinx.