Construir documentação¶
Antes de fazer qualquer alteração na documentação de BeeWare, é útil confirmar que pode compilar a documentação existente.
Antes de criar a documentação, e ter um [ambiente de desenvolvimento] configurado.
Você tem de ter um interpretador Python 3.13 instalado e disponível em seu caminho (isto é, python3.13 tem de iniciar um interpretador Python 3.13).
BeeWare usa o tox para criar a documentação. Os seguintes comandos tox têm de ser executados no mesmo local que o ficheiro tox.ini, que está no diretório raiz do projeto.
Antevisão da documentação em tempo real¶
Para suportar edição rápida da documentação, BeeWare tem um modo de "antevisão em tempo real".
A pré-visualização em tempo real vai compilar com avisos!
O serviço em tempo real está disponível para iteração nas suas atualizações de documentação. Enquanto estiver no processo de atualizar coisas, pode introduzir um problema de marcação. Os problemas considerados WARNING farão com que uma compilação standard falhe; no entanto, o serviço em tempo real está configurado para indicar avisos na saída da consola, enquanto continua a compilar. Isto permite que faça iterações sem precisar reiniciar a antevisão em tempo real.
Um WARNING é diferente de um ERROR. Se introduzir um problema que seja considerado um ERROR, o serviço em tempo real vai falhar e precisar de ser reiniciado. Ele não será iniciado novamente até que o problema WARNING esteja resolvido.
Para iniciar o servidor de tempo real:
(venv) $ tox -e docs-live
(venv) $ tox -e docs-live
(venv) C:\...>tox -e docs-live
Isto vai compilar a documentação, iniciar um servidor Web para servir a documentação, e observar o sistema de ficheiros em busca de alterações na fonte da documentação.
Após o servidor ter arrancado, vai ver algo parecido com o seguinte na saída da consola:
INFORMAÇÃO - [11:18:51] A servir em http://127.0.0.1:8000/
Abra um navegador e navegue até ao URL fornecido. Agora pode começar a iteração na documentação. Se uma alteração for detetada, a documentação será recompilada e qualquer navegador que estiver a visualizar a página modificada será atualizado automaticamente.
O docs-live é um passo inicial
A execução do docs-live para trabalhar com o servidor ativo destina-se a iteração inicial. Você deve sempre executar uma compilação local antes de enviar um pedido de puxar.
Compilação local¶
Quando terminar a iteração, vai precisar fazer uma compilação local da documentação. Este processo de compilação foi desenhado para falhar se houver algum problema de marcação. Isso permite-lhe capturar qualquer coisa que possa ter passado despercebida com o servidor em tempo real.
Gerar uma compilação local¶
Para gerar uma compilação local:
(venv) $ tox -e docs
(venv) $ tox -e docs
(venv) C:\...>tox -e docs
O resultado desta compilação vai estar no diretório _build na raiz do projeto.
Gerar uma compilação local traduzida¶
A documentação de BeeWare está traduzida em vários idiomas. As atualizações na documentação em Inglês têm o potencial de provocar problemas nas compilações dos outros idiomas. É importante verificar se todas as compilações estão a funcionar antes de submeter um pedido de puxar.
Para gerar uma compilação de todas as traduções disponíveis:
(venv) $ tox -e docs-all
(venv) $ tox -e docs-all
(venv) C:\...>tox -e docs-all
O resultado de cada compilação de idioma vai estar no diretório _build/html/<languagecode> associado, onde <languagecode> é o código de idioma de dois ou cinco caracteres associado ao idioma específico (ex., fr para Francês, it para Italiano, etc.).
Se encontrar um problema com uma única compilação, poderá executar essa compilação individual em separado, executando tox -e docs-<languagecode>. Por exemplo, para compilar somente a documentação em Francês, execute:
(venv) $ tox -e docs-fr
(venv) $ tox -e docs-fr
(venv) C:\...>tox -e docs-fr
O resultado de uma compilação num único idioma vai estar no diretório _build.
Análise sintática da documentação¶
O processo de compilação vai identificar problemas de Markdown, mas BeeWare realiza algumas verificações adicionais de estilo e formatação, análises sintáticas conhecidas como "linting". Para executar as verificações de linting:
(venv) $ tox -e docs-lint
(venv) $ tox -e docs-lint
(venv) C:\...>tox -e docs-lint
Isso vai validar que a documentação não contém:
- hiperligações mortas
- palavras com erros ortográficos
Se uma ortografia válida de uma palavra for identificada como incorreta, adicione a palavra à lista em docs/spelling_wordlist. Isto vai adicionar a palavra ao dicionário do corretor ortográfico. Ao adicionar palavras a essa lista, lembre-se:
- Preferimos a ortografia dos EUA, com algumas liberdades para o coloquial específico da programação (ex., "apps") e a verbalização de substantivos (ex., "scrollable")
- Qualquer referência a um nome de um produto deve usar a capitalização preferencial do produto. (por exemplo, "macOS", "GTK", "pytest", "Pygame", "PyScript").
- Se um termo estiver a ser usado "como código", ele deverá ser citado como literal (
assim) em vez de ser adicionado ao dicionário.
Depois de criar os documentos com sucesso, vai estar pronto para escrever a documentação.