为类参考手册贡献

注解

本指南也可以在YouTube上以 video tutorial on YouTube <https://www.youtube.com/watch?v=5jeHXxeX-JY&gt; _.

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

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

  • 分叉和克隆Godot仓库

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

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

注解

如果你是Godot使用的版本控制系统Git的新手,请阅读 GitHub’s interactive guide <https://try.github.io/levels/1/challenges/1&gt; _.你会学到一些基本的词汇,并对这个工具有所了解.

分叉Godot

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

在计算机上克隆存储库:

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

创建一个新的分支来进行你的修改.这使得你的改进与其他文档编写者的同步变得更加容易.如果你遇到任何关于Git的问题,也更容易清理你的仓库.

  1. git checkout -b your-new-branch-name

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

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

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

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

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

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

  1. git remote -v

你应该有两个: origin ,Git默认添加的你在GitHub上的fork和你刚刚添加的 upstream :

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

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

  1. git pull --rebase upstream master

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

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

  1. git fetch upstream
  2. git reset --hard upstream master

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

另一个办法是删除你正在工作的分支,将主分支与Godot仓库同步,然后创建一个新的分支:

  1. git checkout master
  2. git branch -d your-new-branch-name
  3. git pull --rebase upstream master
  4. git checkout -b your-new-branch-name

如果你现在感到迷茫,请到我们的 IRC channels <https://webchat.freenode.net/?channels=#godotengine&gt; _ 来寻求帮助.有经验的Git用户会给你提供帮助的.

更新文档模板

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

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

这样,doc/classes中的XML文件应该是最新的,符合当前Godot引擎的特性.然后你可以用 git diff 命令检查哪些地方有变化.如果除了你打算记录的类之外,其他类也有变化,请在开始编辑模板之前先提交这些变化:

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

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

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

推送并请求拉取您的更改

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

  1. git add doc/classes/<edited_file>.xml
  2. git commit -m "Explain your modifications."
  3. 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中的类的样子:

  1. <class name="Node2D" inherits="CanvasItem" category="Core">
  2.     <brief_description>
  3.         Base node for 2D system.
  4.     </brief_description>
  5.     <description>
  6.         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.
  7.     </description>
  8.     <methods>
  9.         <method name="set_pos">
  10.             <argument index="0" name="pos" type="Vector2">
  11.             </argument>
  12.             <description>
  13.                 Sets the position of the 2D node.
  14.             </description>
  15.         </method>
  16.         [...]
  17.         <method name="edit_set_pivot">
  18.             <argument index="0" name="arg0" type="Vector2">
  19.             </argument>
  20.             <description>
  21.             </description>
  22.         </method>
  23.     </methods>
  24.     <members>
  25.         <member name="global_position" type="Vector2" setter="set_global_position" getter="get_global_position" brief="">
  26.         </member>
  27.         [...]
  28.         <member name="z_as_relative" type="bool" setter="set_z_as_relative" getter="is_z_relative" brief="">
  29.         </member>
  30.     </members>
  31.     <constants>
  32.     </constants>
  33. </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] 中,始终使用 四个空格 进行缩进(解析器将删除制表符).例如:

  1. [codeblock]
  2. func _ready():
  3.     var sprite = get_node("Sprite")
  4.     print(sprite.get_pos())
  5. [/codeblock]

将显示为:

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

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

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

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

  1. [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]“开头的段落.注意使用斜体代替粗体:

  1. [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 存储库中开启一个问题.