在类参考手册中贡献

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

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

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

注解

您可以在Youtube上观看这个指南的 视频

如何贡献

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

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

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

警告

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

开始使用GitHub

如果您是Git和Github的新手,这个指南会帮助您入门。您将学会:

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

注解

如果您是git,即Godot使用的版本控制系统的新手,请阅读 GitHub的交互式指南 。您将学习一些必要的词汇并了解该工具。

分叉Godot

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

在计算机上克隆存储库:

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

创建一个新分支以进行更改。它使您的改进与其他文档编写者同步变得容易得多,如果您对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

您应该有两个:origin ,您在github上的fork,默认添加的git,以及您刚添加的 upstream

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 分支的状态。它将丢弃所有本地更改。确保仅在进行重要更改 之前 运行此命令 。

另一个选择是删除您正在处理的分支,将主分支与Godot存储库同步,并创建一个全新的分支:

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

如果您现在感到迷茫,请来我们的 IRC频道 并寻求帮助。经验丰富的git用户会帮助您。

更新文档模板

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

./bin/godot.x11.tools.64 --doctool .

然后,doc/classes中的xml文件应该与当前的Godot引擎功能保持同步。然后,您可以使用 git diff 命令检查更改的内容。如果其他类的更改超出了您计划记录的类,请在开始编辑模板之前先提交这些更改:

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请求拉取请求。

警告

虽然您可以在GitHub上编辑文件,但不建议这样做。由于数百名贡献者在Godot工作,git历史必须保持清洁。每个提交都应捆绑您对类参考手册所做的所有相关改进、新功能、错误修复……当您从GitHub进行编辑时,每次要保存时,它都会创建一个新分支和一个拉取请求。如果在您的更改得到审核之前几天过去了,您将无法干净地更新到最新版本的存储库。此外,从GitHub保持干净的缩进更难。它们在文档中非常重要。

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

如何编辑类XML

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

使用您喜欢的文本编辑器编辑它。如果使用代码编辑器,请确保它不会更改缩进样式:XML的制表符和BBcode样式块中的4个空格。以下更多关于该内容。

如果您需要在生成的文档中检查所做的修改是否正确,按照 这里 的描述构建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>
            Set 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 ++或类似的编辑器,快速编辑文件。使用搜索功能快速查找类。

使用BBcode样式标签改进格式

Godot的类参考手册支持类似BBcode的标记。它们为文本添加了很好的格式。这是可用标签的列表:

标签 效果 用法 结果
[Class] 链接到一个类 移动[Sprite]。 移动 class_Sprite
[method methodname] 链接到此类中的方法 调用[method hide]。 参见 hide
[method Class.methodname] 链接到另一个类的方法 调用[method Spatial.hide]。 参见 hide
[member membername] 链接到这个类的成员 获得[member scale]。 获得 scale
[member Class.membername] 链接到另一个类的成员 获得 [member Node2D.scale]。 获得 scale
[signal signalname] 链接到此类中的信号 发射 [signal renamed]。 发射 renamed
[signal Class.signalname] 链接到另一个类的信号 发射 [signal Node.renamed]。 发射 renamed
[b] [/b] 粗体 一些[b]粗体[/b]文字。 一些 粗体 文字。
[i] [/i] 斜体 一些[i]斜体[/i]文字。 一些 斜体 文字。
[code] [/code] 等宽字体 一些[code]等宽字体[/code] 文本。 一些 等宽字体 文本。
[codeblock] [/codeblock] 多行预格式化块 见下文。 见下文。

对预格式化的代码块使用 [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())

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

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

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

本地化

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

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

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