为类参考手册贡献

注解

本指南也在 YouTube 上以视频教程的形式提供.

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

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

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

参见

不知道从哪里开始作出贡献? 在 这里 查看当前的类引用完成状态.

如何贡献

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

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

  1. 分叉 Godot 存储库

  2. 在电脑上克隆您的分叉

  3. doc/classes/ 中编辑类文件以写入文档

  4. 提交您的更改并把它们推到您的分叉上

  5. 在Godot存储库上拉取请求

警告

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

开始使用GitHub

如果你是Git和GitHub的新手, 本指南将帮助你入门. 你将学会:

  • 分叉和克隆Godot仓库

  • 保持分叉与其他贡献者同步

  • 创建拉取请求, 以便您的改进最终在官方文档中

注解

如果你是 Godot 使用的版本控制系统 Git 的新手, 请阅读 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 ,Git默认添加的你在GitHub上的fork和你刚刚添加的 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 channels <https://webchat.freenode.net/?channels=#godotengine> _ 来寻求帮助. 有经验的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编辑时, 每次你想保存时, 它都会创建一个新的分支和一个Pull Request. 如果过了几天你的修改才得到审查, 你就不能干净利落地更新到最新版本的仓库. 另外, 要从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>
                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 ++或类似的编辑器, 快速编辑文件. 使用搜索功能快速查找类.

改进BBCode风格标签的格式

Godot的类参考支持类似BBCode的标签. 它们为文本添加了漂亮的格式. 下面是可用标签的列表:

标签

效果

用法

结果

[Class]

链接到一个类

移动[Sprite].

移动 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] 文本.

一些 等宽字体 文本.

[kbd] [/kbd]

键盘和鼠标快捷键

一些[kbd]Ctrl + C[/kbd]键.

一些 Ctrl + C 键.

[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())

要表示重要信息, 请在描述末尾添加一段以 "[b]注:[/b]" 开头的内容:

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

为了表示如果不仔细遵循可能导致安全问题或数据丢失的关键信息, 请在描述末尾添加一段以 "[b]警告:[/b]" 开头的内容:

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

对于不推荐使用的属性, 请添加以 "[i]deprecated.[/i]" 开头的段落. 注意使用斜体代替粗体:

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

在上面描述的所有段落中, 确保标点符号是BBCode标签的一部分, 以保持一致性.

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

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

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

本地化

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

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

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