正如您可能已经注意到的，最近 GNOME 开发者文档网站上发生了一些各种变化。这些变化也影响了 GTK 及其核心依赖项的 API 参考。
发生了什么变化
主要的变化是 GTK 将其 API 参考和辅助文档迁移到了一个新的文档工具，称为 gi-docgen。与之前的文档工具 gtk-doc 不同，gi-docgen 使用基于 GObject 的库生成的内省数据来构建 API 参考。这有多个好处：
- gi-docgen 更容易运行并集成到现有库中，因为它只有一个项目描述文件，并且依赖于内省数据来完成其他所有操作；此外，它可以很容易地作为 Meson 子项目包含进来。
- gi-docgen 到处都使用 Markdown，而不是 DocBook。
- gi-docgen 速度明显更快，因为它不需要额外的源代码解析步骤；它没有通过
xsltproc进行 XML 到 HTML 转换的瓶颈；并且在生成参考后，它不必解析 Devhelp 文件来修复与其他库的交叉引用。 - gi-docgen 可以推断出更多关于 API 的信息，因为它有权访问库的整个内省数据，包括其依赖项；这允许自动生成更准确和一致的文档，而不是依赖人工来完成这项工作。
- gi-docgen 为所有 API 入口点和附加文档生成稳定的 URL，这意味着更容易链接到它，而无需使用晦涩的引用。
- 默认文档模板可以在不同的外形尺寸和布局上使用；它尊重支持它的 Web 浏览器上的暗黑主题选项；并提供不依赖于第三方服务的树内实时搜索功能。
- gi-docgen 也可以在树外运行——这在以后会派上用场。
除了这些改进之外，使用内省数据作为文档的来源还有其他好处：它使我们在向非 C 用户公开的 API 类型方面保持诚实；并且它使 C API 参考更接近于使用相同数据的其他语言的参考。
GTK4、Pango 和 GdkPixbuf 已迁移到这个新工具，并且在迁移过程中，我们也审查了文档以提高其一致性和准确性，特别是对于 API 中较旧的部分。
新的 API 参考可以通过 Devhelp 41 离线使用，该版本将于 9 月与 GNOME 41 一起发布。
在线文档
GTK 参考的规范在线位置现在是 docs.gtk.org。在那里您会找到以下内容的 API 参考：
GTK3 和 ATK 的 API 参考也已移至 docs.gtk.org。
docs.gtk.org 网站由 GTK CI 管道生成，因此它始终与存储库的状态保持同步；由于 gi-docgen 支持树外构建，该网站还可以为尚未移植到 gi-docgen 的各种库（如 GLib、GTK3 和 ATK）生成文档。
已知问题
当然，任何大的变化都会带来副作用。
主要问题是文档 URL 的更改；引用 developer.gnome.org 上位置的现有文档必须进行修复。感谢 GNOME 系统管理员，我们已经设置了一些重定向，并且有一些关于如何改进它们的想法，而不会创建无法维护的静态重定向混乱。
新的文档网站正在被各种搜索引擎索引；您使用它和链接到它的次数越多，新的参考资料就越容易在排名中上升。无论如何，我们强烈建议您使用搜索功能：只需按“s”即可开始搜索符号和类型，甚至搜索额外文档页面中的内容。
不幸的是，鉴于 C API 的底层性质，GLib 的内省数据存在一些问题；我们正在努力改进这一点，这将不仅影响文档，还会影响 API 在其他语言中的整体绑定能力。
GLib、GObject、GIO 和 GTK3 的文档仍然是为 gtk-doc 编写的；这意味着文档中的交叉链接可能无法工作；内容可能无法很好地呈现；或者可能存在冗余段落。这将在未来得到修复，通过 gi-docgen 中的更改（如果可能）以及更新库本身的文档。这也将改进语言绑定文档，因为它们使用与 gi-docgen 相同的内省数据。非常欢迎在此方面提供帮助。