Godot离线中文文档生成方法

起因

因为网络问题，需要下载godot离线文档以供查询。但在官方渠道下能下载到的只有文档的英文最新版本的离线版本。内容可能对不上，也没能利用好官方的中文资源。所以自己下载了godot文档源码并生成了中文版本，过程记录如下，以防遗忘。

文档源码下载

官方文档源码下载地址：https://github.com/godotengine/godot-docs/tree/master
可以利用git拉到本地并切换到指定版本的分支，或者在网页上切换好版本分支后直接下载。
我这里需要的是4.2版本的文档。

上面下载的源码只有英文版本，我们还需要另行下载语言支持资源包。我们将官方文档源码拷贝至资源包目录下的docs文件夹中。

当然，你完全可以通过git先拉取godot文档的语言支持资源，再通过submodule自动拉取对应版本的官方文档生成脚本与资源，这是更理想的做法。

生成环境准备

python与Sphinx

文档基于Sphinx生成，可以根据需要生成html或者pdf等不同格式的版本。
我们首先需要准本3.x版本的python，并使用python安装Sphinx

pip install sphinx=="7.0.0"

这里没有用最新版sphinx，而是使用7.0版本是因为：笔者完成文档生成时，最新版本的sphinx貌似出现了问题，无法顺利生成godot文档，故根据https://github.com/sphinx-doc/sphinx/issues里相关的说法改成了7.0版本。

读者可以试着使用最新版本，视具体情况决定是否改换版本。

安装完sphinx之后，需要下载sphinx的rtd主题插件

pip install sphinx-rtd-theme

文档源码修改

进入官方文档源码目录（即docs文件夹下）
打开conf.py，开头可以看见一些需要的sphinx扩展与依赖

# Sphinx extension module names and templates location
sys.path.append(os.path.abspath("_extensions"))
extensions = [
    "sphinx_tabs.tabs",
    "notfound.extension",
    "sphinxext.opengraph",
    "sphinx_copybutton",
]

如果缺少的话，可以通过pip下载。比如上面的几个扩展，可以通过下面的命令下载：

pip install sphinx-tabs
pip install sphinx-notfound-page
pip install sphinxext-opengraph
pip install sphinx-copybutton

再往下，可以看到语言选项的一段代码，大致如下：

language = os.getenv("READTHEDOCS_LANGUAGE", "en")

将里面的en更改为zh_CN。
保存修改并退出。

生成

打开命令行，进入源码根目录（即docs），输入

./make html

或者

./make pdf

生成对应格式的离线文档，过程可能比较长。
如果生成过程中报错缺少包，pip安装指定的包即可。
文档生成结束后，会自动生成一个_build文件夹，我们需要的可读文档就在这个路径下。

最后

感谢godot社区里文档翻译人员的辛苦付出。