Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

添加文档

备注

只有在 Godot 4.3 及更高版本中才能为 GDExtensions 添加文档。

GDExtension 文档系统的工作方式与内置引擎文档类似。它使用一系列 XML 文件（每个类一个）来记录每个类暴露的构造函数、属性、方法、常量、信号和主题项。

首先，找到项目的测试项目文件夹 ，其中应该包含一个已安装并运行你的扩展的 Godot 项目。如果你使用的是 godot-cpp-template ，则你的 GDExtension 项目已经包含一个 project 文件夹 。或者，可以按照 新手入门 中描述的步骤添加一个。在 project 文件夹中，运行以下终端命令：

# Replace "godot" with the full path to a Godot editor binary
# if Godot is not installed in your `PATH`.
godot --doctool ../ --gdextension-docs

此命令指示 Godot 通过 --doctool 和 --gdextension-docs 命令生成文档。 ../ 参数指定 GDExtension 的基本路径。

运行此命令后，你应该可以在 GDExtension 项目的 doc_classes 文件夹内找到已注册 GDExtension 类的 XML 文件。现在你就可以编辑它们，但对于本教程而言，空文件就足够了。

现在已经有了包含文档的 XML 文件，下一步是将它们包含在 GDExtension 二进制文件中。假设使用 SCons 作为构建系统，你可以将以下代码添加到 SConstruct 文件中。如果你使用的是 godot-cpp-template ，则文件中已经包含相关代码。

if env["target"] in ["editor", "template_debug"]:
    doc_data = env.GodotCPPDocData("src/gen/doc_data.gen.cpp", source=Glob("doc_classes/*.xml"))
    sources.append(doc_data)

if 语句可以避免将文档添加到不需要的 GDExtension 发布版本中。然后，SCons 会加载 doc_classes 目录中的所有 XML 文件，并将生成的目标文件添加到 sources 数组中，以便包含在 GDExtension 构建中。

构建完成后，请重新启动你的 Godot 项目。你可以通过在脚本编辑器中对类名使用 Ctrl + Click，或者在编辑器帮助对话框中查找对应类，来打开某个扩展类的文档。如果一切顺利，你应该会看到类似下面的内容：

../../../_images/gdextension_docs_generation.webp

编写和设置文档样式

类参考 XML 文件的格式与 Godot 自身使用的格式完全相同。其具体说明可以参考文档：类参考入门。

如果你想了解如何编写高质量的文档，可以参考 Godot 的 documentation guidelines。

在线发布文档

你可能希望像本网站一样，为你的 GDExtension 发布在线类参考文档。最重要的一步是从 XML 类参考生成 reStructuredText（.rst）文件：

# You need a version.py file, so download it first.
curl -sSLO https://raw.githubusercontent.com/godotengine/godot/refs/heads/master/version.py

# Edit version.py according to your project before proceeding.
# Then, run the rst generator. You'll need to have Python installed for this command to work.
curl -sSL https://raw.githubusercontent.com/godotengine/godot/master/doc/tools/make_rst.py | python3 - -o "docs/classes" -l "en" doc_classes

你的 .rst 文件现在可以在 docs/classes/ 目录中找到。从这里开始，你可以使用任何支持 reStructuredText 语法的文档构建工具来生成网站。

godot-docs 使用 Sphinx。你可以将该仓库作为基础来构建自己的文档系统。以下指南描述了基本步骤，但并不详尽：你仍需要自行摸索一部分内容才能让它正常工作。

  1. 把 godot-docs 作为子模块添加到你的 docs/ 文件夹中。

  2. 将其 conf.py、index.rst、.readthedocs.yaml 文件复制到 /docs/ 目录下。之后你可以决定复制并编辑更多 godot-docs 的文件，例如 _templates/layout.html。

  3. 根据你的项目修改这些文件。这主要包括调整路径，使其指向 godot-docs 子文件夹，以及修改相关字符串，以表明你正在构建的是你的项目文档，而不是 Godot 的文档。

  4. 在 readthedocs.org 上创建一个账号。导入你的项目，并将 .readthedocs.yaml 文件的路径修改为 /docs/.readthedocs.yaml。

完成所有这些步骤后，你的文档应该可以在 <repo-name>.readthedocs.io 上访问。