Documentação da construção¶
Antes de fazer qualquer alteração na documentação de BeeWare Docs Tools, é útil confirmar que pode compilar a documentação existente.
Antes de criar a documentação, configure um [ambiente de desenvolvimento].
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 Docs Tools 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 Docs Tools tem um modo de "antevisão em tempo real".
A pré-visualização em tempo real vai compilar com avisos!
O servidor ativo está disponível para que possa testar as atualizações da sua documentação. Enquanto estiver no processo de atualização, pode introduzir um problema de marcação. Problemas classificados como WARNING vão fazer com que uma compilação standard falhe; no entanto, o servidor ativo está configurado para indicar os avisos na saída da consola, enquanto continua a compilação. Isso permite que faça iterações sem precisar reiniciar a antevisão ao vivo.
Um WARNING é diferente de um ERROR. Se introduzir um problema considerado um ERROR, o servidor ativo vai falhar e precisar de ser reiniciado. Ele não vai voltar a funcionar até que o problema ERROR 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 Docs Tools 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 Docs Tools 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, você estará pronto para escrever a documentação.