Documentação da construção¶
Antes de fazer qualquer alteração na documentação de BeeWare, é útil confirmar que você pode criar a documentação existente.
Antes de criar a documentação, configure um [ambiente de desenvolvimento].
Você deve ter um interpretador Python 3.13 instalado e
disponível em seu caminho (ou seja, python3.13 deve
iniciar um interpretador Python 3.13).
BeeWare utiliza o tox para criar a documentação. Os comandos tox a
seguir devem ser executados no mesmo local que o arquivo tox.ini, que está no
diretório raiz do projeto.
Visualização da documentação em tempo real¶
Para dar suporte à edição rápida da documentação, BeeWare tem um modo de "visualização ao vivo".
A pré-visualização ao vivo será criada com avisos!
O serviço ao vivo está disponível para iterar em suas atualizações de
documentação. Enquanto estiver no processo de atualização, você poderá
introduzir um problema de marcação. Os problemas considerados WARNING farão
com que uma compilação padrão falhe; no entanto, o serviço ao vivo está
configurado para indicar avisos na saída do console, enquanto continua a
compilação. Isso permite que você faça iterações sem precisar reiniciar a
visualização ao vivo.
Um WARNING é diferente de um ERROR. Se você introduzir um problema que seja
considerado um ERROR, o serviço ao vivo falhará e precisará ser reiniciado.
Ele não será iniciado novamente até que o problema WARNING seja resolvido.
Para iniciar o servidor ativo:
(venv) $ tox -e docs-live
(venv) $ tox -e docs-live
(venv) C:\...>tox -e docs-live
Isso criará a documentação, iniciará um servidor da Web para servir a documentação e observará o sistema de arquivos em busca de alterações na fonte da documentação.
Quando o servidor for iniciado, você verá algo parecido com o seguinte na saída do console:
INFO - [11:18:51] Serving on http://127.0.0.1:8000/
Abra um navegador e navegue até o URL fornecido. Agora você pode começar a iterar na documentação. Se uma alteração for detectada, a documentação será reconstruída e qualquer navegador que estiver visualizando a página modificada será atualizado automaticamente.
O docs-live é uma etapa inicial
A execução do docs-live para trabalhar com o servidor ativo destina-se à
iteração inicial. Você deve sempre executar uma compilação local antes de
enviar uma solicitação pull.
Construção local¶
Quando terminar a iteração, você precisará fazer uma compilação local da documentação. Esse processo de compilação foi projetado para falhar se houver algum problema de marcação. Isso permite que você capture qualquer coisa que possa ter passado despercebida no servidor ativo.
Geração de 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 dessa compilação estará no diretório _build na raiz do projeto.
Geração de uma compilação local traduzida¶
A documentação da BeeWare está traduzida em vários idiomas. As atualizações na documentação em inglês podem levar a problemas nas compilações em outros idiomas. É importante verificar se todas as compilações estão funcionando antes de enviar uma solicitação pull.
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
A saída de cada compilação de idioma estará no diretório
_build/html/<languagecode> associado, em que <languagecode> é o código de
idioma de dois ou cinco caracteres associado ao idioma específico (por exemplo,
fr para francês, it para italiano etc.).
Se você encontrar um problema com uma única compilação, poderá executar essa
compilação individual separadamente, 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
A saída de uma compilação em um único idioma estará no diretório _build.
Linting de documentação¶
O processo de compilação identificará problemas de Markdown, mas BeeWare realiza algumas verificações adicionais de estilo e formatação, 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 validará que a documentação não contém:
- hiperlinks mortos
- 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. Isso 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 coloquialismo específico da programação (por exemplo, "apps") e a verbalização de substantivos (por exemplo, "scrollable")
- Qualquer referência ao nome de um produto deve usar a capitalização preferencial do produto. (por exemplo, "macOS", "GTK", "pytest", "Pygame", "PyScript").
- Se um termo estiver sendo usado "como código", ele deverá ser citado como um
literal (
como este) em vez de ser adicionado ao dicionário.
Depois de criar os documentos com sucesso, você estará pronto para escrever a documentação.