Primeiros passos¶

Configurando seu projeto e ambiente de desenvolvimento¶

Em um novo diretório, crie um arquivo chamado README.rst com o seguinte conteúdo.

README.rst¶

Lumache
=======

**Lumache** (/lu'make/) is a Python library for cooks and food lovers that
creates recipes mixing random ingredients.

É um bom momento para criar um ambiente virtual Python e instalar as ferramentas necessárias. Para isso, abra um terminal de linha de comando, cd no diretório que você acabou de criar, e execute os seguintes comandos:

$ python -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install sphinx

Nota

O método de instalação usado acima é descrito com mais detalhes em Pacote PyPI. No restante deste tutorial, as instruções presumirão estar um ambiente virtual Python.

Se você executou essas instruções corretamente, deverá ter as ferramentas de linha de comando do Sphinx disponíveis. Você pode fazer uma verificação básica executando este comando:

(.venv) $ sphinx-build --version
sphinx-build 4.0.2

Se você vir uma saída semelhante, você está no caminho certo!

Criando o layout da documentação¶

Em seguida, na linha de comando, execute o seguinte comando:

(.venv) $ sphinx-quickstart docs

Isto apresentará a você uma série de perguntas necessárias para criar o diretório básico e o layout de configuração do seu projeto dentro da pasta docs. Para prosseguir, responda a cada pergunta da seguinte forma:

> Separar os diretórios de origem e de construção (y/n) [n]: Escreva “y” (sem aspas) e pressione Enter.
> Nome do projeto: Escreva “Lumache” (sem aspas) e pressione Enter.
> Nome(s) de autor(es): Escreva “Graziella” (sem aspas) e pressione Enter.
> Lançamento do projeto []: Escreva “0.1” (sem aspas) e pressione Enter.
> Idioma do projeto [en]: Deixe vazio (o padrão, inglês) e pressione Enter.

Após a última pergunta, você verá o novo diretório docs com o seguinte conteúdo.

docs
├── build
├── make.bat
├── Makefile
└── source
   ├── conf.py
   ├── index.rst
   ├── _static
   └── _templates

O objetivo de cada um desses arquivos é:

build/: Um diretório vazio (por enquanto) que conterá a documentação renderizada.
make.bat e Makefile: Scripts de conveniência para simplificar algumas operações comuns do Sphinx, como renderizar o conteúdo.
source/conf.py: Um script Python que contém a configuração do projeto Sphinx. Ele contém o nome do projeto e a versão que você especificou em sphinx-quickstart, bem como algumas chaves de configuração extras.
source/index.rst: O documento raiz do projeto, que serve como página de boas-vindas e contém a raiz da “árvore do índice” (ou toctree).

Graças a esta etapa de inicialização, você já tem tudo o que precisa para renderizar a documentação como HTML pela primeira vez. Para fazer isso, execute este comando:

(.venv) $ sphinx-build -M html docs/source/ docs/build/

E finalmente, abra docs/build/html/index.html em seu navegador. Você deverá ver algo assim:

Aqui vamos nós! Você criou sua primeira documentação HTML usando o Sphinx. Agora você pode começar a personalizá-la.