贡献文档

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

参见

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

入门

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

参见

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

警告

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

Godot 文档是什么

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

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

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

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

将修改投稿

拉取请求应该默认使用 master 分支。请在修改只对特定版本的 Godot 有意义时,才针对其他分支(比如 2.13.0)提交拉取请求。

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

编辑现有页面

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

参见

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

在线编辑页面

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

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

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

  2. 在您转到的 GitHub 页面上,点击右上角靠近 RawBlameHistory 按钮的铅笔图标。它的工具提示是“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引用名称开始页面:

.. _doc_insert_your_title_here:

Insert your title here
======================

引用 _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/ 目录中,起一个有意义的名字,然后在页面中加入:

.. image:: img/image_name.png

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

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

许可证

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

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