为 Weblate 文档作贡献¶
欢迎您改进您选择的文档页面。通过单击页面右上角的 在 GitHub 上编辑 按钮轻松完成此操作。
文档准则¶
请在写作时遵守以下准则：
如果部分文档有效请不要将其删除。
请使用清晰易懂的语言。你正在写技术文档，而不是一首诗。并非所有文档读者都是母语人士，请深思熟虑。
如果你不确定不要害怕询问。如果你在编辑时必须询问某些功能。在你得到答案之前不要改变它的文档。这意味着你要么改变。要么询问。不要同时做这两件事。
在遵循文档的同时通过执行描述的操作来验证您的更改。
发送带有小块更改的PR以便更轻松更快速地查看和合并。
如果你想重写和改变一篇大文章的结构，请分两步进行：
重写
重写的内容经审核、润色并被合并后，在另一个 PR 中修改段落的结构。
本地构建文档¶
也可以在本地编辑并构建文档，Python 要求位于 pyproject.toml 中的 docs 依赖群。如果已经在使用完整的开发环境，那么 uv sync --all-extras --dev 就够了。如果只为了文档工作，那么 uv sync --group docs 就够了。
推荐的本地工作流是：
make -C docs update-docs
./ci/run-docs
ci/run-docs 包装器构建文档会将警告视为错误。
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.
提示
您还需要安装 graphviz 来构建文档。
翻译文档¶
你可以 翻译文档。
更新所生成的文档片段¶
几个文档部分使用从代码生成的模板。刷新它们的首选方式是：
make -C docs update-docs
此目标重新生成文档当前使用的文本片段，包括：
附加组件事件、内置附加组件、常见附加组件参数
机器翻译服务
文件格式参数和文件格式特性表
权限和内置角色
检查和检查标记
在文档总页面保留手动维护的文本，而非将其添加到自动生成的文本片段中。例如，附加组件 包括事件的三个生成文件、内置附加组件和常见附加组件参数，而废弃的附加组件直接在该页面中维护。
如果你需要只重新生成一个部分，在 管理命令 中记录了单独的管理命令，在 docs/Makefile 中列出了 update-docs 所用的准确命令。