Contributing to the class reference

注解

This guide also is available as a video tutorial on YouTube.

Godot提供了许多节点和单例来帮助您开发游戏。每个节点都是一个类，记录在 类参考手册 中。这个参考手册对于任何学习该引擎的人来说都是必不可少的：它既可以在线也可以在引擎中使用。

但参考手册尚未完善。有些方法、变量和信号缺乏描述。其他则随着最新版本进行了更改，需要更新。开发人员不能自己编写整个参考手册。Godot需要您和我们所有人为此做出贡献。

重要: 如果您打算进行较大的更改或做出更大的贡献，通常最好创建一个问题(或在现有问题中发表评论)，让其他人知道，以便他们不会也开始从事同一件事。

参见

不知道从哪里开始作出贡献? 来看看目前的类基准的完成状态`在这里，<https://godotengine.github.io/doc-status/>`__.

如何贡献

类参考手册位于Godot的GitHub存储库中 doc/classes/ 路径下的XML文件中。

有5个步骤来更新类参考手册(接下来会谈到完整指南)：

1. 分叉 Godot存储库
2. 在电脑上克隆您的分叉
3. 在 doc/classes/ 中编辑类文件以写入文档
4. 提交您的更改并把它们推到您的分叉上
5. 在Godot存储库上拉取请求

警告

总是使用这些XML文件来编辑API参考手册。不要编辑托管在 godot-docs 存储库中，在 在线文档 中生成的.rst文件。

开始使用GitHub

If you’re new to Git and GitHub, this guide will help you get started. You’ll learn to:

• 分叉和克隆Godot仓库
• 保持分叉与其他贡献者同步
• 创建拉取请求，以便您的改进最终在官方文档中

注解

If you’re new to Git, the version control system Godot uses, go through GitHub’s interactive guide. You’ll learn some essential vocabulary and get a sense for the tool.

分叉Godot

分叉Godot引擎到您自己的GitHub存储库。

在计算机上克隆存储库：

git clone https://github.com/your_name/godot.git

Create a new branch to make your changes. It makes it a lot easier to sync your improvements with other docs writers. It’s also easier to clean up your repository if you run into any issues with Git.

git checkout -b your-new-branch-name

在您开始编写API文档之前，新分支与主分支相同。在 doc / 文件夹中，您将找到类参考手册。

如何使本地克隆保持最新状态

其他编写者为Godot的文档做出了贡献。您的本地存储库将落后于它，您将不得不同步它。特别是如果其他贡献者在您处理它时更新类参考手册。

首先添加一个 upstream git remote 来使用。远程数据库是您可以从在线存储库中下载新文件的链接。

git remote add upstream https://github.com/godotengine/godot

您可以使用以下命令检查所有远程服务器的列表：

git remote -v

You should have two: origin, your fork on GitHub that Git adds by default, and upstream, that you just added:

origin  https://github.com/your_name/godot.git (fetch)
origin  https://github.com/your_name/godot.git (push)
upstream        https://github.com/godotengine/godot.git (fetch)
upstream        https://github.com/godotengine/godot.git (push)

每次要将分支同步到上游存储库的状态时，请输入：

git pull --rebase upstream master

此命令将首先 获取(fetch)，或下载最新版本的Godot存储库。然后，它将重新应用您的本地更改。

如果您进行了更改，且不希望保留在本地分支中，则请使用以下命令：

git fetch upstream
git reset --hard upstream master

警告： 上述命令会将分支重置为 upstream master 分支的状态。它将丢弃所有本地更改。确保仅在进行重要更改 之前 运行此命令 。

Another option is to delete the branch you’re working on, synchronize the master branch with the Godot repository, and create a new branch:

git checkout master
git branch -d your-new-branch-name
git pull --rebase upstream master
git checkout -b your-new-branch-name

If you’re feeling lost by now, come to our IRC channels and ask for help. Experienced Git users will give you a hand.

更新文档模板

在源代码中修改类时，文档模板可能会过时。为了确保您正在编辑最新版本，首先需要编译Godot(您可以按照 构建系统介绍 页面)，然后运行以下命令(假设64位Linux)：

./bin/godot.x11.tools.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. If there are changes to other classes than the one you are planning to document, please commit those changes first before starting to edit the template:

git add doc/classes/*.xml
git commit -m "Sync classes reference template with current code base"

您现在可以编辑此文件以添加内容。

注意： 如果最近已由其他撰稿人完成，则您不必强行执行这些步骤(除非您知道您计划编辑的类最近 已 被修改过)。

推送并请求拉取您的更改

完成修改后，在GitHub存储库上推送您的更改：

git add doc/classes/<edited_file>.xml
git commit -m "Explain your modifications."
git push

完成后，您可以通过Godot分叉的GitHub UI请求拉取请求。

警告

Although you can edit files on GitHub, it’s not recommended. As hundreds of contributors work on Godot, the Git history must stay clean. Each commit should bundle all related improvements you make to the class reference, a new feature, bug fixes… When you edit from GitHub, it will create a new branch and a Pull Request every time you want to save it. If a few days pass before your changes get a review, you won’t be able to update to the latest version of the repository cleanly. Also, it’s harder to keep clean indents from GitHub. And they’re very important in the docs.

总结：如果您不知道自己在做什么，请不要编辑GitHub中的文件。

如何编辑类XML

在 doc/classes/ 中编辑所选类的文件以更新类参考手册。该文件夹包含每个类的XML文件。XML列出了您在类参考手册中找到的常量和方法。Godot自动生成并更新XML。

Edit it using your favorite text editor. If you use a code editor, make sure that it doesn’t change the indent style: tabs for the XML, and 4 spaces inside BBCode-style blocks. More on that below.

如果您需要在生成的文档中检查所做的修改是否正确，按照 这里 的描述构建Godot，运行编辑器并打开您所修改页面的帮助。

如何编写类参考手册

每个类都有一个简述和一个长的描述。简述始终位于页面顶部，而完整描述位于方法、变量和常量列表下方。方法、成员变量、常量和信号在不同的类别或XML节点中。对于以上每个，了解它们如何在Godot的源代码中工作，并填写它们的 <description>。

我们的工作是在这些标记之间添加缺少的文本：

• <description></description>
• <brief_description></brief_description>
• <constant></constant>
• <method></method>
• <member></member>
• <signal></signal>

用清晰简单的语言编写。始终遵循 撰写指南 以使您的描述简短易读。在描述中 不要留下空行：XML文件中的每一行都将生成一个新段落。

以下是XML中的类的样子：

<class name="Node2D" inherits="CanvasItem" category="Core">
    <brief_description>
        Base node for 2D system.
    </brief_description>
    <description>
        Base node for 2D system. Node2D contains a position, rotation and scale, which is used to position and animate. It can alternatively be used with a custom 2D transform ([Matrix32]). A tree of Node2Ds allows complex hierarchies for animation and positioning.
    </description>
    <methods>
        <method name="set_pos">
            <argument index="0" name="pos" type="Vector2">
            </argument>
            <description>
                Sets the position of the 2D node.
            </description>
        </method>
        [...]
        <method name="edit_set_pivot">
            <argument index="0" name="arg0" type="Vector2">
            </argument>
            <description>
            </description>
        </method>
    </methods>
    <members>
        <member name="global_position" type="Vector2" setter="set_global_position" getter="get_global_position" brief="">
        </member>
        [...]
        <member name="z_as_relative" type="bool" setter="set_z_as_relative" getter="is_z_relative" brief="">
        </member>
    </members>
    <constants>
    </constants>
</class>

使用代码编辑器，如Vim、Atom、Code、Notepad ++或类似的编辑器，快速编辑文件。使用搜索功能快速查找类。

Improve formatting with BBCode style tags

Godot’s class reference supports BBCode-like tags. They add nice formatting to the text. Here’s the list of available tags:

对预格式化的代码块使用 [codeblock]。在 [codeblock] 中，始终使用 四个空格 进行缩进(解析器将删除制表符)。例如：

[codeblock]
func _ready():
    var sprite = get_node("Sprite")
    print(sprite.get_pos())
[/codeblock]

将显示为：

func _ready():
    var sprite = get_node("Sprite")
    print(sprite.get_pos())

To denote important information, add a paragraph starting with “[b]Note:[/b]“ at the end of the description:

[b]Note:[/b] Only available when using the GLES2 renderer.

To denote crucial information that could cause security issues or loss of data if not followed carefully, add a paragraph starting with “[b]Warning:[/b]“ at the end of the description:

[b]Warning:[/b] If this property is set to [code]true[/code], it allows clients to execute arbitrary code on the server.

For deprecated properties, add a paragraph starting with “[i]Deprecated.[/i]“. Notice the use of italics instead of bold:

[i]Deprecated.[/i] This property has been replaced by [member other_property].

In all the paragraphs described above, make sure the punctuation is part of the BBCode tags for consistency.

我不知道这个方法干什么用！

没问题。将其留下，并在您请求提取更改时列出跳过的方法。别的编写者会处理它。

您仍然可以在GitHub上查看Godot源代码中方法的实现。此外，如果您有疑问，请随时在 问答网站 和IRC(freenode，#godotengine)上询问。

本地化

在 Hosted Weblate 上的文档可以被翻译成任何语言。

翻译后的字符串由文档维护人员在 godot-docs-l10n 存储库中手动同步更新。

具有良好完成程度的语言具有自己的手册本地化实例。如果您认为新语言足够完整可以获得自己的实例，请在 godot-docs-l10n 存储库中开启一个问题。