為 Weblate 說明文件作出貢獻

歡迎您來改進您選擇的說明文件頁面。點擊符號 編輯在頁面的右上角的github 按鈕上輕鬆進行。

說明文件指導原則

請在寫作時尊重這些指導原則：

  1. 如果有效，請勿刪除部分文件。

  2. 使用清晰易懂的語言。您正在寫科技作家，而不是一首詩。並非所有Docs讀者都是母語人士，很沉思。

  3. Don’t be afraid to ask if you are not certain. If you have to ask about some feature while editing, don’t change its docs before you have the answer. This means: You change or ask. Don’t do both at the same time.

  4. 通過在遵循文件時執行描述的操作來驗證您的變更。

  5. 將PR與小塊的變更發送，以便更容易，更快地查看和合併。

  6. 如果要重寫並變更大文章的結構，請分兩步執行以下操作：

    1. 重寫

    2. 一旦重寫，檢閱，拋光和合併，改變另一條公關的段落的結構。

Building the documentation locally

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.

推薦的本地工作流程是：

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

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

提示

You will also need graphviz installed to build the documentation.

翻譯說明文件

You can translate the docs.

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

  • 機器翻譯服務

  • 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, 附加元件 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 管理指令, and the exact commands used by update-docs are listed in docs/Makefile.