文件编制指南¶
如果您希望通过编写或审阅文档或翻译现有文档来为Godot引擎做出贡献,则本页介绍要遵循的规则。还可以查看 godot-docs GitHub repository 以及 docs front page 关于要遵循哪些步骤以及如何联系Docs团队。
如何贡献¶
创建或修改文档页面主要通过 godot-docs GitHub repository . HTML(或PDF和EPUB)文档是从该存储库中的.rst文件(restructuredtext标记语言)生成的。修改拉请求中的页面并将其合并将触发联机文档的重建。
参见
有关git用法和请求工作流的详细信息,请参阅 请求工作流 页。它描述的关于主godoengine/godot存储库的大部分内容对于docs存储库也是有效的。
readme.md文件包含启动所需的所有信息,请阅读。特别是,它包含一些提示和技巧,以及指向有关重构的文本标记语言的参考文档的链接。
警告
如果要编辑 API引用 ,请注意 not 在Godot文档库中完成。相反,您应该编辑 doc/classes/*
godot的主存储库的XML文件。这些文件随后用于生成编辑器中的文档以及联机文档的API引用。阅读更多信息: 有助于类引用 .
“在Github上编辑”链接¶
如果你正在阅读 docs.godotengine.org
您将在页面右上角看到“在Github上编辑”超链接。创建Github帐户后,可以对正在阅读的页面提出如下更改建议:
复制github链接指向的URL。URL的一部分引用了版本名,如“3.1”或“最新”。将此部分替换为单词“master”,使结果如下所示:
https://github.com/godotengine/godot-docs/blob/master/community/contributing/docs_writing_guidelines.rst
在浏览器中加载该URL。
在Github页面上,单击铅笔图标。它有工具提示“编辑此项目分叉中的文件”。
完成要对该页进行的所有编辑。
总结您在页面底部表单中所做的更改,完成后单击标记为“建议文件更改”的按钮。
在以下屏幕上,单击“创建拉请求”按钮,直到看到类似的消息
Open. yourGitHubUsername wants to merge 1 commit into godotengine:master from yourGitHubUsername:patch-6
评审员将评估您的变更,并将其纳入到文档中,如果他们被认为需要改进的话。还可能要求您在包含更改之前对其进行修改。
什么是好的文档?¶
文件应以简单的英语书写,使用格式良好的句子和不同层次的章节。它应该是清晰和客观的。也可以看看 文档编写指南 .
我们通过以下定义将教程页面与其他文档页面区分开来:
教程:旨在解释如何在编辑器或脚本中使用一个或多个概念以达到特定的学习目的的页面(例如,“制作一个简单的二维乒乓游戏”,“对一个对象施加力”)。
文档:在可能的情况下,一次只准确描述一个概念的页面(例如sprite类的方法列表,或godot中输入管理的概述)。
只要您遵守以下规则(以及回购协议上的规则),您可以自由编写您希望的文档类型。
标题¶
始终以其标题和狮身人面像引用名称开始页面:
.. _doc_insert_your_title_here:
Insert your title here
======================
引用允许使用 :ref:
格式,例如 :ref:`doc_insert_your_title_here
`将链接到上面的示例页(注意引用中缺少前导下划线)。
另外,要避免使用美国的camelcase标题:标题的第一个词应该以大写字母开头,而后面的每一个词都不应该以大写字母开头。因此,这是一个很好的例子:
在此处插入标题
这是一个坏例子:
在此处插入标题
只有项目、人员和节点类名称的首字母应大写。
许可¶
本文档及其包含的每一页都是根据 Creative Commons Attribution 3.0 license (CC-BY-3.0) ,归因于“Juan Linietsky, Ariel Manzur和Godot社区”。
通过在Github存储库上提供文档,您同意您的更改是根据此许可证分发的。