Open rainyq69 opened 2 years ago
目前的问题是:将文档托管到 rtd 后,没有一个自动化脚本执行 reset_docstring,导致中文文档无法上传。
rtd 的机制是自动执行 sphinx-build,所以这一步需要更改。
进一步调研得出,上边的结论是错误的。其实不需要管 rtd 的构建机制,因为自定义操作可以在 sphinx 指定的 conf.py 中完成前置操作,于是新的解决步骤为:
os.system("bash command")
的方式下载所需的包,然后通过 setuptools 构建 docresetimport cn
自动完成 docstring 的文档中文化其中遇到的问题有:
os.system("bash command")
不能改变解释器的所在路径,所以需要使用 && 把需要切换路径的命令连接起来python setup.py install
加上 --user 选项解决,但此方法对 rtd 虚拟环境不适用
目前找到的 sphinx 管理版本的插件有:
初步判定不会采取此方案,因为这些插件都长时间未维护,与新版本的 sphinx 兼容性太差,要想使用只能魔改源码。
其中遇到的问题有:
现在你是怎么做的流程能更清楚地描述下吗。可能用更主流的方式去做,就不会遇到这种问题?
参考 https://docs.readthedocs.io/en/stable/config-file/v2.html#python 这里的说明。
貌似是可以直接指定 pypi 上的依赖包,以及本地的依赖包的。
现在你是怎么做的流程能更清楚地描述下吗。
具体做法是对 conf.py 做修改,从而完成 sphinx 生成 rst 文件前的一些前置初始化操作(在我们这里,就是将原有的英文 docstring 替换为中文版本)。 修改历史在这里:https://github.com/rainyq69/oneflow-api-cn/commits/0.8.0
貌似是可以直接指定 pypi 上的依赖包,以及本地的依赖包的。
这个我现在去研究一下,稍后给出结论。
我的想法 在 read the doc 增加一个 oneflow_cn 还是指向 oneflow 仓库,但是和英文版本不同的 docs 目录 中文英文版本互相提供跳转链接
在 read the doc 增加一个 oneflow_cn 还是指向 oneflow 仓库,但是和英文版本不同的 docs 目录
这个想法的最终效果是把中英文 API 文档统一管理在一个仓库中吗?
貌似是可以直接指定 pypi 上的依赖包,以及本地的依赖包的。
确实如此,但这能不能解决我们的问题需要稍后做个测试。毕竟 readthedocs “下手”的对象是 docstring,我们要在它根据 docstring 生成 rst 文件之前改动 docstring,而这一步需要我们导入的包,但依赖 readthedocs 的配置文件导入包的时机有可能不对。
我刚才突然想起来一个更简单直观的方法,就是新建一个副本,内容就是已经把中文替换好了的新的 docs 目录,然后把这个上传到 readthedocs 上做源码。每次我们更新现有的 oneflow-api-cn 中的内容,副本仓库/分支会响应我们的变化,重新做一遍替换字符串操作。这样我们就不必在 readthedocs 提供的“黑盒”容器中做前置的中文替换操作了。
貌似是可以直接指定 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
也可以。
你做这些事情有很重要的前提,需要你自己花时间:
光看这个issue,还不清楚你对两者熟悉到什么程度了。
如果 sphinx 那里不好设置环境变量,你直接把这个环境变量的判断去掉,直接
import cn
也可以。
这个工作我已经做了,在这里:https://github.com/rainyq69/oneflow-api-cn/commit/b49c23b16efb1613a7f2781cc2a61c2ba3fa7c57
目前已经成功生成文档,但依然存在问题(接下来我会定位出错点尝试自行解决):
sys.path.insert()
临时添加包搜索路径)参数
、返回
等字眼(已解决,这是 readthedocs 自动检索到 arguments
、return
后自行加上的,下边的繁体版有所印证。同时这也说明 import nn
没有凑效,需要进一步排查)
无法找到通过 pip 下载的 furo 包,临时使用 classic 主题
为什么不可以呢,oneflow 仓库可以,这个仓库就应该可以。你是怎么做的呢。请你以后附带上你的操作,方便其他人帮忙分析判断。这已经强调过好几次了。
生成的文档中英参半
这个问题列在这里,和此 issue 要解决的 “版本管理” 是由直接关联的吗,我理解就是简单的没有翻译完而已? 还是说你发现,采用版本管理,就会出现中英参半的文档?
这个问题列在这里,和此 issue 要解决的 “版本管理” 是由直接关联的吗,我理解就是简单的没有翻译完而已? 还是说你发现,采用版本管理,就会出现中英参半的文档?
导致中英参半的问题还没有准确定位到。 截图里也展示了,这并不是没有翻译完的问题。翻译的代码原封未动。
为什么不可以呢,oneflow 仓库可以,这个仓库就应该可以。你是怎么做的呢。请你以后附带上你的操作,方便其他人帮忙分析判断。这已经强调过好几次了。
我今天早上是先在这里记录一下进度,没想到您立马就看到了。等下我就展示我的操作。
为中文 API 文档添加版本管理过程中遇到的问题和可行的解决方案
两种方案:
该 issue 中的一切尝试都体现在此处。但这个 commit 历史十分凌乱,因此我会在某些 comment 中引用具体的 commit 来展示我的操作。