中文 API 文档版本管理

[rainyq69]

为中文 API 文档添加版本管理过程中遇到的问题和可行的解决方案

两种方案：

• 通过 readthedocs 托管
• 通过 GitHub actions 托管
  • 寻找 sphinx 的管理版本插件

该 issue 中的一切尝试都体现在此处。但这个 commit 历史十分凌乱，因此我会在某些 comment 中引用具体的 commit 来展示我的操作。

[rainyq69]

目前的问题是：将文档托管到 rtd 后，没有一个自动化脚本执行 reset_docstring，导致中文文档无法上传。

rtd 的机制是自动执行 sphinx-build，所以这一步需要更改。

---

进一步调研得出，上边的结论是错误的。其实不需要管 rtd 的构建机制，因为自定义操作可以在 sphinx 指定的 conf.py 中完成前置操作，于是新的解决步骤为：

1. 通过 os.system("bash command") 的方式下载所需的包，然后通过 setuptools 构建 docreset
2. 通过 import cn 自动完成 docstring 的文档中文化
3. 剩下的交给 rtd 照常生成页面并发布

其中遇到的问题有：

1. rtd 会自动生成一个虚拟环境，它要求 pip 不能使用 --user 选项
2. 因为 os.system("bash command") 不能改变解释器的所在路径，所以需要使用 && 把需要切换路径的命令连接起来
3. 需要在虚拟环境中添加包搜索路径，因为这个虚拟环境貌似没有服务器实例上的全局概念（总之加上之后问题解决了）
4. 现在的问题是找不到 _docreset，可是前边的构建过程（使用 pybind11 和 setup）明明没有报错，目前猜测是 setup 构建工具在虚拟环境和服务器环境中表现不一致造成的
5. 在本地复现出了这个问题，通过将 python setup.py install 加上 --user 选项解决，但此方法对 rtd 虚拟环境不适用

[rainyq69]

目前找到的 sphinx 管理版本的插件有：

• SCVersioning
• sphinx-multiversion
• reno
• sphinx-versions

初步判定不会采取此方案，因为这些插件都长时间未维护，与新版本的 sphinx 兼容性太差，要想使用只能魔改源码。

[doombeaker]

其中遇到的问题有：

现在你是怎么做的流程能更清楚地描述下吗。可能用更主流的方式去做，就不会遇到这种问题？

参考 https://docs.readthedocs.io/en/stable/config-file/v2.html#python 这里的说明。

貌似是可以直接指定 pypi 上的依赖包，以及本地的依赖包的。

[rainyq69]

现在你是怎么做的流程能更清楚地描述下吗。

具体做法是对 conf.py 做修改，从而完成 sphinx 生成 rst 文件前的一些前置初始化操作（在我们这里，就是将原有的英文 docstring 替换为中文版本）。 修改历史在这里：https://github.com/rainyq69/oneflow-api-cn/commits/0.8.0

[rainyq69]

貌似是可以直接指定 pypi 上的依赖包，以及本地的依赖包的。

这个我现在去研究一下，稍后给出结论。

[jackalcooper]

我的想法 在 read the doc 增加一个 oneflow_cn 还是指向 oneflow 仓库，但是和英文版本不同的 docs 目录 中文英文版本互相提供跳转链接

[rainyq69]

在 read the doc 增加一个 oneflow_cn 还是指向 oneflow 仓库，但是和英文版本不同的 docs 目录

这个想法的最终效果是把中英文 API 文档统一管理在一个仓库中吗？

[rainyq69]

貌似是可以直接指定 pypi 上的依赖包，以及本地的依赖包的。

确实如此，但这能不能解决我们的问题需要稍后做个测试。毕竟 readthedocs “下手”的对象是 docstring，我们要在它根据 docstring 生成 rst 文件之前改动 docstring，而这一步需要我们导入的包，但依赖 readthedocs 的配置文件导入包的时机有可能不对。

我刚才突然想起来一个更简单直观的方法，就是新建一个副本，内容就是已经把中文替换好了的新的 docs 目录，然后把这个上传到 readthedocs 上做源码。每次我们更新现有的 oneflow-api-cn 中的内容，副本仓库/分支会响应我们的变化，重新做一遍替换字符串操作。这样我们就不必在 readthedocs 提供的“黑盒”容器中做前置的中文替换操作了。

[doombeaker]

貌似是可以直接指定 pypi 上的依赖包，以及本地的依赖包的。

确实如此，但这能不能解决我们的问题需要稍后做个测试。毕竟 readthedocs “下手”的对象是 docstring，我们要在它根据 docstring 生成 rst 文件之前改动 docstring，而这一步需要我们导入的包，但依赖 readthedocs 的配置文件导入包的时机有可能不对。

我刚才突然想起来一个更简单直观的方法，就是新建一个副本，内容就是已经把中文替换好了的新的 docs 目录，然后把这个上传到 readthedocs 上做源码。每次我们更新现有的 oneflow-api-cn 中的内容，副本仓库/分支会响应我们的变化，重新做一遍替换字符串操作。这样我们就不必在 readthedocs 提供的“黑盒”容器中做前置的中文替换操作了。

我们现在也是原生的用 sphinx build 的，只是 conf.py 里 import cn 了而已：

https://github.com/Oneflow-Inc/oneflow-api-cn/blob/master/docs/source/conf.py#L22

如果 sphinx 那里不好设置环境变量，你直接把这个环境变量的判断去掉，直接 import cn 也可以。

你做这些事情有很重要的前提，需要你自己花时间：

1. 你要非常清楚 oneflow-api-cn 是怎么中文化的
2. 你要非常清楚 readthedocs 是怎么 build 文档的

光看这个issue，还不清楚你对两者熟悉到什么程度了。

[rainyq69]

如果 sphinx 那里不好设置环境变量，你直接把这个环境变量的判断去掉，直接 import cn 也可以。

这个工作我已经做了，在这里：https://github.com/rainyq69/oneflow-api-cn/commit/b49c23b16efb1613a7f2781cc2a61c2ba3fa7c57

[rainyq69]

目前已经成功生成文档，但依然存在问题（接下来我会定位出错点尝试自行解决）：

1. 无法找到通过 pip 下载的 furo 包，临时使用 classic 主题（已解决，方案是通过 sys.path.insert() 临时添加包搜索路径）
2. 文档的英文只有部分被替换为了中文，比如参数、返回等字眼（已解决，这是 readthedocs 自动检索到 arguments、return 后自行加上的，下边的繁体版有所印证。同时这也说明 import nn 没有凑效，需要进一步排查）

[doombeaker]

无法找到通过 pip 下载的 furo 包，临时使用 classic 主题

为什么不可以呢，oneflow 仓库可以，这个仓库就应该可以。你是怎么做的呢。请你以后附带上你的操作，方便其他人帮忙分析判断。这已经强调过好几次了。

生成的文档中英参半

这个问题列在这里，和此 issue 要解决的 “版本管理” 是由直接关联的吗，我理解就是简单的没有翻译完而已？ 还是说你发现，采用版本管理，就会出现中英参半的文档？

[rainyq69]

这个问题列在这里，和此 issue 要解决的 “版本管理” 是由直接关联的吗，我理解就是简单的没有翻译完而已？ 还是说你发现，采用版本管理，就会出现中英参半的文档？

导致中英参半的问题还没有准确定位到。 截图里也展示了，这并不是没有翻译完的问题。翻译的代码原封未动。

[rainyq69]

为什么不可以呢，oneflow 仓库可以，这个仓库就应该可以。你是怎么做的呢。请你以后附带上你的操作，方便其他人帮忙分析判断。这已经强调过好几次了。

我今天早上是先在这里记录一下进度，没想到您立马就看到了。等下我就展示我的操作。