文档规范

本页介绍了如果你想通过编写或审阅文档, 或翻译现有的文档来为Godot引擎做贡献, 需要遵循的规则. 另外, 请看 godot-docs GitHub仓库的README 和 docs front page , 了解应该遵循哪些步骤以及如何联系docs团队.

如何贡献

创建或修改文档页面主要通过 godot-docs GitHub 仓库 来完成.HTML(或PDF和EPUB)文档是从该仓库中的.rst文件(reStructuredText标记语言)生成的. 在拉取请求中修改这些页面并将其合并将触发重建在线文档.

参见

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

警告

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

警告

如果你想编辑 API参考手册 , 请注意它 不 应该在godot-docs仓库中完成. 而是, 你应该编辑Godot的主仓库的 doc/classes/* XML文件. 这些文件随后将用于生成编辑器内文档以及在线文档的API参考手册. 在这里 为类参考手册贡献 阅读更多.

“Edit on GitHub”链接

如果你正在阅读 docs.godotengine.org 上的文档, 你会在页面的右上方看到一个 Edit on GitHub 的超链接. 一旦你创建了GitHub账户, 你就可以对你正在阅读的页面提出修改意见, 方法如下:

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

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

  3. 完成您要对该页面进行的所有编辑.

  4. 在页面底部的表格中总结你所做的修改, 完成后点击标有 Propose file change 的按钮.

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

  6. 审核者会评估你的修改, 如果你的修改可以接受, 就把它们纳入文档. 可能还会要求您对更改进行修改, 然后再将其包括在内.

什么是良好的文档？

文件应该用通俗的英语写好，使用格式良好的句子和不同层次的章节和分节。它应该是清晰和客观的。另请参阅 文档编写规范。

我们通过以下定义将教程页面与其他文档页面区分开:

  • 教程: 该页面旨在说明如何在编辑器或脚本中使用一个或多个概念, 以达到具有学习目的的特定目标(例如”制作简单的2d Pong游戏 “,” 向对象施加力”).

  • 文档: 一个页面, 如果可能的话, 一次只描述一个且只有一个概念(例如Sprite类的方法列表, 或者Godot中输入管理的概述).

只要您遵守以下规则(以及储存库中的规则), 你可以自由地编写你想的那种文档.

标题

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

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

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

另外, 避免使用美国驼峰式标题: 标题的第一个单词应以大写字母开头, 而后面的每个单词都不应该大写. 因此, 这是一个很好的示例:

  • Insert your title here

这是一个糟糕的示例:

  • Insert Your Title Here

只有项目, 人员和节点类名称应该首字母大写.

翻译现有页面

您可以帮助我们翻译或校对在 Hosted Weblate 上的官方 Godot 文档。

翻译状态

还有官方的 Godot i18n 仓库，在那里你可以看到数据最近一次同步的时间。

许可证

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

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