贡献文档

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

参见

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

入门

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

参见

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

警告

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

Godot 文档是什么

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

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

  1. 写作指南. There, you will find rules and recommendations to write in a way that everyone understands.

  2. 内容规范. They explain the principles we follow to write the documentation and the kind of content we accept.

将修改投稿

Pull requests should use the master branch by default. Only make pull requests against other branches (e.g. 3.6 or 4.2) if your changes only apply to that specific version of Godot. After a pull request is merged into master, it will usually be cherry-picked into the current stable branch by documentation maintainers.

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

编辑现有页面

To edit an existing page, locate its .rst source file and open it in your favorite text editor. You can then commit the changes, push them to your fork, and make a pull request. Note that the pages in classes/ should not be edited here. They are automatically generated from Godot's XML class reference. See 为类参考手册贡献 for details.

参见

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

在线编辑页面

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

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

  1. 点击 Edit on GitHub 按钮。

  2. On the GitHub page you're taken to, make sure the current branch is "master". Click the pencil icon in the top-right corner near the Raw, Blame, and Delete buttons. It has the tooltip "Fork this project and edit the file".

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

  4. Click "Commit changes...", summarize the changes you made and make sure to replace the placeholder "Update file.rst" by a short, but clear one-line description, as this is the commit title. Click the button Propose changes.

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

备注

If there are more commits than your own in the pull request it is likely that your branch was created using the wrong origin, due to "master" not being the current branch in step 2. You will need to rebase your branch to "master" or create a new branch.

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

添加新页面

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

  1. 搜索已有 Issue 或者提交新 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

Only proper nouns, projects, people, and node class names should have their first letter capitalized.

Sphinx 与 reStructuredText 语法

Check Sphinx's reST Primer and the official reference for details on the syntax.

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

添加图片及附件

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

.. image:: img/image_name.webp

或者，你可以使用 figure 指令，该指令使图像具有对比边框并允许将其集中在页面上。

.. figure:: img/image_name.webp
    :align: center

You can also include attachments as support material for a tutorial, by placing them into a files/ folder next to the .rst file, and using this inline markup:

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

Consider using the godot-docs-project-starters <https://github.com/godotengine/godot-docs-project-starters> repository for hosting support materials, such as project templates and asset packs. You can use a direct link to the generated archive from that repository with the regular link markup:

`file_name.zip <https://github.com/godotengine/godot-docs-project-starters/releases/download/latest-4.x/file_name.zip>`_

许可证

This documentation and every page it contains is published under the terms of the Creative Commons Attribution 3.0 license (CC BY 3.0), with attribution to "Juan Linietsky, Ariel Manzur and the Godot community".

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