贡献文档

本指南介绍的是如何向 Godot 的文档做出贡献，无论是编写页面还是审核页面。

参见

如果你想要将页面或类参考从英语翻译为其他语言，请阅读 编辑器和文档本地化。

入门

要修改或创建参考手册中的页面，你需要编辑 godot-docs GitHub 仓库中的 .rst 文件。如果在拉取请求中修改了这些文件，合并时就会触发在线文档的重新构建。

参见

有关Git用法和拉取请求工作流程的详细信息, 请参阅 拉取请求工作流程 页面. 它描述的关于主godotengine/godot仓库的大部分内容, 这对文档仓库也是有效的.

警告

类参考的源文件位于 Godot 引擎仓库中。我们会用它来生成本文档的 Godot API 章节。如果你想要更新类、方法、属性等的描述信息，请参阅 为类参考手册贡献。

Godot 文档是什么

Godot 文档旨在作为 Godot 游戏引擎的完备参考手册。除了“入门”章节的两个游戏制作教程之外，不包含渐进式教程。

我们致力于使用简单通顺的语言编写实事求是的内容。投稿前请阅读：

  1. 文档编写规范。为了让写出的内容让所有人都能够理解，你可以在这里找到相关的规定和建议。

  2. 内容规范。对我们在编写文档时所遵循的原则进行了解释，也解释了我们接受哪些形式的内容。

将修改投稿

拉取请求应该默认使用 master 分支。请在修改只对特定版本的 Godot 有意义时，才针对其他分支（比如 2.1 或 3.0）提交拉取请求。

虽然编辑器来不如百科方便，但是我们就是在这个 Git 仓库中编写文档的。可以在版本控制系统中直接访问源文件，对于保证我们文档的质量是有利的。

编辑现有页面

要编辑已有页面，请先定位其 .rst 源文件并在你喜欢的文本编辑器中打开。然后你就可以将修改提交、推送到你的 Fork 中，然后创建拉取请求。注意，请勿在此编辑 classes/ 中的页面。它们是根据 Godot 的 XML 类参考自动生成的。详情请参阅 为类参考手册贡献。

参见

要在你的电脑上构建手册并测试修改，请参阅 使用 Sphinx 构建手册。

在线编辑页面

点击每一页右上角的 Edit on GitHub 链接即可在线编辑该文档。

这样你就会跳转到 GitHub 文本编辑器，要拥有 GitHub 账户并登录才能够使用。登录后，可以这样提出修改方案：

  1. 点击“Edit on GitHub”按钮。

  2. 在您转到的 GitHub 页面上，点击右上角靠近 Raw、Blame、History 按钮的铅笔图标。它的工具提示是“Edit the file in a fork of this project”，在这个项目的 Fork 中编辑该文件。

  3. 在文本编辑器中编辑文本。

  4. 请在网页的底部总结你所作出的修改，然后单击 Propose file change（提议修改文件）按钮。请确保已经把占位的“Update file.rst”替换成了简短的单行描述，因为这会成为提交的标题。

  5. 在接下来的页面上，点击 Create pull request（创建拉取请求）按钮，直到看到类似 Username wants to merge 1 commit into godotengine:master from Username:patch-6 的信息。

另一个贡献者会适合你的修改，如果修改没有问题的话，就会把它们合并进文档。在合并之前，他们可能还会进行一些修改，或者要求您自己进行修改。

添加新页面

在添加新页面之前，请确保它适合现有文档：

  1. 搜索已有 Issue <https://github.com/godotengine/godot-docs/issues>或者提交新 Issue，确认该页面是必须的。

  2. 确认目前不存在涉及该话题的页面。

  3. 阅读我们的 内容规范。

要添加一个新页面，请在想要的章节下创建一个 .rst 文件并起一个有意义的名字，例如 tutorials/3d/light_baking.rst。

你应该将你的页面加入相关的“toctree”（目录，例如 tutorials/3d/index.rst）。请将你的新文件名加入目录列表中，使用相对路径，不要带扩展名，例如 light_baking。

标题

始终以标题和Sphinx引用名称开始页面:

  1. .. _doc_insert_your_title_here:
  3. Insert your title here
  4. ======================

引用 _doc_insert_your_title_here 应该和标题相匹配。

引用允许使用 :ref: 格式链接到这个页面，例如 :ref:`doc_insert_your_title_here` 将链接到上面的例子页面（注意引用中没有前导下划线）。

请以普通句子的形式编写标题，不要所有单词都大写：

  • 良好：Understanding signals in Godot

  • 欠佳：Understanding Signals In Godot

专有名词、项目、人物、节点名称等才应该首字母大写。

Sphinx 与 reStructuredText 语法

语法详情请查看 Sphinx 的 reST Primer 及其官方参考手册。

Sphinx 会利用特定的 reST 注释来执行特定的操作，比如定义目录（.. toctree::）或者进行页面之间的交叉引用。详情请查看 Sphinx 官方文档。要学习如何使用 .. note::、.. seealso:: 等 Sphinx 指令，请查看 Sphinx 指令文档。

添加图片及附件

要添加图片，请将它们放入 .rst 旁的 img/ 目录中，起一个有意义的名字，然后在页面中加入：

  1. .. image:: img/image_name.png

添加附件的操作也与之类似，比如添加作为教程支持材料的素材，就可以先将它们放入 .rst 文件旁的 files/ 文件夹，然后使用这样的行内标记：

  1. :download:`myfilename.zip <files/myfilename.zip>`

许可证

本文档及其包含的每个页面均根据 知识共享署名3.0许可证(CC-BY-3.0)) 的条款发布, 归属于”Juan Linietsky,Ariel Manzur和Godot社区”.

通过贡献GitHub仓库上的文档, 你同意你的更改是根据此许可证分发的.