Oneflow-Inc/oneflow-documentation

对于带 : 如 tuple of python:ints 的文档编译错误问题

zhongshsh opened this issue · 1 comments

问题

在 docString 的参数描述(Args)中,如 input (oneflow.Tensor): the Input Tensor,第一个冒号会被解析成 rst 的指令,实现参数前缀 input (oneflow.Tensor) 识别。但是当出现如 dim (int or tuple of python:ints, optional): the dimension to reduce. 前缀有冒号的情况,rst 无法准确识别,在第一个冒号 python:ints 处进行截断,导致解析出的文档不符合预期。

image

分析和解决方案

实际在 PyTorch 源码中,是这么编写的:dim (int or tuple of ints): the dimension or dimensions to reduce.。即 python: 是编译过程中自动产生的。因此现在的解决方法是使用 tuple of ints 取代 tuple of python:ints ,编译效果如下:

image

其他

OneFlow 中有些文档直接使用了会编译出错的写法,已替换。有些就直接没写参数类型,待补全。

image

谢谢shanshan反馈,请 @robin978 在重构 v0.8.0 的过程中注意下这个问题,修正过来。

shanshan同学的描述应该已经很清楚了,如果还有不了解的,请 @rainyq69 协助 tingyu。