Contribua para a documentação do Weblate¶
É bem-vindo para melhorar a página de documentação de sua escolha. Faça isso facilmente a clicar no botão Editar no GitHub no canto superior direito da página.
Linhas diretrizes da documentação¶
Por favor, respeite estas linhas diretrizes quando escrever:
Não remova parte da documentação se ela for válida.
Use uma linguagem clara e de fácil compreensão. Está a escrever documentos técnicos, não um poema. Nem todos os leitores de documentos são falantes nativos, fique atento.
Não tenha medo de perguntar se não tem certeza. Se tiver que perguntar sobre algum recurso durante a edição, não altere os documentos dele antes de ter a resposta. Isso significa: ou muda ou pergunta. Não faça os dois ao mesmo tempo.
Verifique as suas alterações a executar as ações descritas ao seguir os documentos.
Envie PR com alterações em pequenos pedaços para tornar mais fácil e rápido revisar e mesclar.
Se quiser reescrever e alterar a estrutura de um grande artigo, faça isso em duas etapas:
Reescreva
Depois que a reescrita for revisada, polida e mesclada, altere a estrutura dos parágrafos em outro PR.
Criar documentação localmente¶
A documentação também pode ser editada e criada localmente; os requisitos do Python estão no grupo de dependência docs em pyproject.toml. Se já usa o ambiente de desenvolvimento completo, uv sync --all-extras --dev é suficiente. Para documentação de trabalho apenas, uv sync --group docs é suficiente.
O fluxo de trabalho local recomendado é:
make -C docs update-docs
./ci/run-docs
O invólucro ci/run-docs compila a documentação com avisos tratados como erros.
Dica
Também precisará do graphviz instalado para criar a documentação.
Traduzir a documentação¶
Pode traduzir os documentos.
Atualizar porções de documentação gerada¶
Várias secções de documentação usam modelos gerados a partir do código. A maneira preferida de atualizá-los é:
make -C docs update-docs
Este alvo regenera as porções atualmente usadas pela documentação, incluindo:
eventos de extras, extras integrados, e parâmetros de extras comuns
Serviços de tradução automática
parâmetros de formato de ficheiro e tabelas de funcionalidades de formato de ficheiro
Permissões e funções integradas
Verificações e marcadores de verificação
Mantém o texto manualmente mantido na página de documentação parente em vez de adicioná-lo a porções automaticamente geradas. Por exemplo, Extensões inclui três ficheiros gerados para eventos, extras integrados e parâmetros de extras comuns, enquanto que extras obsoletos são mantidos diretamente na página.
Se precisa de regenerar apenas uma parte, os comandos de gestão individuais são documentados em Comandos de gestão, e os comandos exatos usados por update-docs são listados em docs/Makefile.