Contribuir com a documentação do Weblate

Você é bem-vindo para melhorar a página de documentação de sua escolha. Faça isso facilmente clicando no botão Editar no GitHub no canto superior direito da página.

Diretrizes na documentação

Respeite essas diretrizes ao escrever:

  1. Não remova parte da documentação se ela for válida.

  2. Use uma linguagem clara e de fácil compreensão. Você está escrevendo documentos técnicos, não um poema. Nem todos os leitores de documentos são falantes nativos, fique atento.

  3. Não tenha medo de perguntar se você não tem certeza. Se você tiver que perguntar sobre algum recurso durante a edição, não altere seus documentos antes de ter a resposta. Isso significa: você muda ou pergunta. Não faça os dois ao mesmo tempo.

  4. Verifique suas alterações executando as ações descritas ao seguir os documentos.

  5. Envie PR com alterações em pequenos pedaços para tornar mais fácil e rápido revisar e mesclar.

  6. Se você quiser reescrever e alterar a estrutura de um grande artigo, faça isso em duas etapas:

    1. Reescreva

    2. Depois que a reescrita for revisada, polida e mesclada, altere a estrutura dos parágrafos em outro PR.

Criar documentação localmente

Documentation can be also edited and built locally, the Python requirements are in the docs dependency group in pyproject.toml. If you already use the full development environment, uv sync --all-extras --dev is enough. For documentation work only, uv sync --group docs is sufficient.

The recommended local workflow is:

make -C docs update-docs
./ci/run-docs

The ci/run-docs wrapper builds the documentation with warnings treated as errors.

CI documentation, release notes, and linkcheck builds reuse cached intersphinx inventories. The Intersphinx inventories workflow refreshes them daily and can also be run manually from GitHub Actions on the default branch. Failed refreshes retain the last valid inventories and are reported as workflow failures.

Inventories are stored in docs/_build/intersphinx. Builds use upstream inventories when a local copy is missing, including after CI cache eviction or when adding an inventory URL. Local and Read the Docs builds do not require the cache. To refresh local copies for all documentation languages, run:

languages=$(uv run --no-project scripts/list-documentation-languages.py)
uv run python docs/_ext/intersphinx_cache.py --languages "${languages#languages=}"

The inventory cache does not eliminate network requests for checking destination pages during linkcheck builds.

Dica

Você também precisará do graphviz instalado para criar a documentação.

Traduzir a documentação

Você pode traduzir os documentos.

Updating generated documentation snippets

Several documentation sections use templates generated from the code. The preferred way to refresh them is:

make -C docs update-docs

This target regenerates the snippets currently used by the documentation, including:

  • add-on events, built-in add-ons, and common add-on parameters

  • machine translation services

  • file format parameters and file format feature tables

  • permissions and built-in roles

  • checks and check flags

Keep manually maintained text in the parent documentation page rather than adding it to autogenerated snippets. For example, Complementos includes three generated files for events, built-in add-ons, and common add-on parameters, while obsolete add-ons are maintained directly in the page.

If you need to regenerate only one part, the individual management commands are documented in Comandos de gerência, and the exact commands used by update-docs are listed in docs/Makefile.