为类参考手册贡献

为类参考手册贡献

类参考是一组描述引擎公开 API 的文章。这些文章中包括了对各种类、方法、属性和全局对象的描述，可用于脚本的编写。类参考可以从文档的侧边栏进入，在线阅读，也可以在 Godot 编辑器中从帮助菜单进入。

随着引擎的发展以及功能的添加或修改，类参考的某些部分会变得过时，为此需要添加新的描述和示例。我们虽然鼓励开发人员在提交拉取请求时，最好在类参考中记录他们的所有工作，但我们不能期望每个人都能够编写高质量的文档，因此总是有需要像你这样的贡献者来完善现有的文档，创建缺失的参考资料。

类参考的源文件

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.

In the main repository the class reference is stored in XML files, one for each exposed class or global object. The majority of these files is located in doc/classes/, but some modules contain their own documentation as well. You will find it in the modules/<module_name>/doc_classes/ directory. To learn more about editing XML files refer to 类参考入门.

参见

至于 Git 用法及拉取请求工作流程的详细信息，请参阅拉取请求工作流程页面。

If you want to translate the class reference from English to another language, see 编辑器和文档的本地化. This guide is also available as a video tutorial on 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.

You can still look at the methods’ implementation in Godot’s source code on GitHub. If you have doubts, feel free to ask on the Q&A website and Godot Contributors Chat.

警告

Unless you make minor changes, like fixing a typo, we do not recommend using the GitHub web editor to edit the class reference’s XML files. It lacks features to edit XML well, like keeping indentations consistent, and it does not allow amending commits based on reviews.

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 文件。

To do so, you first need to compile Godot. See the 构建系统介绍 page to learn how. Then, execute the compiled Godot binary from the Godot root directory with the --doctool option. For example, if you’re on 64-bit Linux, the command might be:

./bin/godot.linuxbsd.editor.x86_64 --doctool

具体的后缀集可能不同。请仔细阅读链接里的文章以了解更多信息。

The XML files in doc/classes/ should then be up-to-date with current Godot Engine features. You can then check what changed using the git diff command.

请仅提交包含与你在 API 上的工作相关的更改。你可以使用 git checkout 来放弃对其他 XML 文件中的更改，但如果注意到不相关的文件正在更新，请考虑一下再报告。理想情况下，运行此命令应该只提交你自己所做的更改。

Previous Next

Built with Sphinx using a theme provided by Read the Docs.