Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
为类参考手册贡献
类参考是一组描述引擎公开 API 的文章。 这些文章中包括了对各种类、方法、属性和全局对象的描述,可用于脚本的编写。类参考可以从文档的侧边栏进入,在线阅读,也可以在 Godot 编辑器中从帮助菜单进入。
As the engine grows and features are added or modified, some parts of the class reference become obsolete and new descriptions and examples need to be added. While developers are required to document their work in the class reference when submitting a pull request, we can't expect every programmer to be a good technical writer. There is always work for contributors like you to polish existing and create missing reference material.
类参考的源文件
As the class reference is available in two places, online and in the editor, we need to take care to keep things in sync. To achieve this the main Godot repository is picked as the source of truth, and the documentation for the class reference is tracked there.
警告
You should not edit .rst
files in the classes/
folder of the
documentation repository.
These files are generated automatically and are synced manually by project
maintainers. Read further to learn how to correctly edit the class reference.
类参考在主仓库中以 XML 文件的形式存储,每个文件对应一个公开的类或全局对象。这些文件大部分位于 doc/classes/ 中,某些模块也会有自带的文档,可以在 modules/<模块名>/doc_classes/
目录中找到。 更多有关编辑 XML 文件的信息见 类参考入门。
参见
至于 Git 用法及拉取请求工作流程的详细信息,请参阅 拉取请求工作流程 页面。
如果你想把类参考手册从英文翻译到其他语言,请参阅 编辑器和文档的本地化。本指南在 YouTube 上也有视频教程版本。
重要:如果你准备进行大量修改,就应该在 godot-docs 仓库中创建 Issue,或者在已有 Issue 上发表评论。这样别人就会知道你准备处理某个类了。
贡献什么
开始贡献的自然位置应当是你最熟悉的类。这确保了添加的描述将基于(你的)经验和必要的专业知识,而不仅仅是方法或属性的名称。 我们建议不要添加省事的描述,无论它看起来多么有吸引力。 这种描述掩盖了对文档的需求,并且很难自动识别。
参见
Following this principle is important and allows us to create tools for contributors. Such as the class reference's completion status tracker. You can use it to quickly find documentation pages missing descriptions.
If you decide to document a class, but don't know what a particular method does, don't worry. Leave it for now, and list the methods you skipped when you open a pull request with your changes. Another writer will take care of it.
你仍然可以在 GitHub 上查看 Godot 的源代码。如果你有疑问,请随时在问答网站和 Godot 贡献者聊天上提问。
警告
除非只是像修正笔误之类的小改动,否则我们不推荐使用 GitHub 的在线编辑器来编辑类参考的 XML 文件。这个编辑器缺少便于编辑 XML 的功能,比如它无法保持缩进的一致性,并且使用在线编辑器无法根据评审的意见对提交进行修正。
It also doesn't allow you to test your changes in the engine or with validation scripts as described in 如何编辑类 XML.
修改引擎时更新类参考
当你创建了一个新的类或者修改了引擎原有的 API 时,就需要重新生成 doc/classes/
中的 XML 文件。
为了达到这个目的,你首先需要编译 Godot。方法请参阅 构建系统介绍 页面。然后在 Godot 根目录中使用 --doctool
选项运行编译出的 Godot 二进制文件。例如在 64 位 Linux 下的命令就是:
./bin/godot.linuxbsd.editor.x86_64 --doctool
具体的后缀集可能不同。 请仔细阅读链接里的文章以了解更多信息。
在 doc/classes/
中的 XML 文件此时应该是与当前 Godot 引擎的特性一致的。你可以使用 git diff
查看不同之处。
请仅提交包含与你在 API 上的工作相关的更改。你可以使用 git checkout
来放弃对其他 XML 文件中的更改,但如果注意到不相关的文件正在更新,请考虑一下再报告。理想情况下,运行此命令应该只提交你自己所做的更改。
接下来你需要为所有新生成的条目提供描述。