调研和排查当前 API 文档中需要改善的接口

[doombeaker]

在 API 文档 https://oneflow.readthedocs.io/en/master/ 中，因为历史遗留问题，存在一些低级的问题。

主要有以下几类问题：

导出了 API，但是没有文档

如：https://oneflow.readthedocs.io/en/master/module.html#oneflow.nn.Module.apply

导出了 API，但是函数原型是空的，并且不正确

如：https://oneflow.readthedocs.io/en/master/oneflow.html#oneflow.tensor

这个 tensor 方法，显然有多个参数，原型并不是 tensor()

解决方法

这类问题常常是因为，直接从 C 导出的接口，文档编译生成系统无法提取到正确的函数原型。因此其实要在 docstring 中的第一行显式写出。

像这样：https://github.com/Oneflow-Inc/oneflow/blob/master/python/oneflow/framework/docstr/array_ops.py#L369

公式格式问题

如：https://oneflow.readthedocs.io/en/master/functional.html#oneflow.nn.functional.hardsigmoid

这类问题是往往是错误使用了 latex 语法。

解决办法就是参考其它显示正确的 docstring，进行修改，编译，知道调整正确后再提交。

任务

需要遍历 https://oneflow.readthedocs.io/en/master/ 中的所有 API，找出有问题的 API，整理成表。方便后续找相应开发解决。

表格

API	问题	API作者	谁解决	PR
nn.Module	缺 docstring
oneflow.tensor	原型错误

[chengtbf]

参考：

• https://docs.nvidia.com/deeplearning/dali/user-guide/docs/supported_ops.html#nvidia.dali.fn.crop_mirror_normalize

[doombeaker]

API 缺文档问题分工

张晓雨

这一类 tensor 方法，大部分只要写 "See xxx" 就可以了。比如：https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.add

• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.sqrt
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.square
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.stride
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.addmm
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.clone
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.cosh
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.data
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.detach
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.diagonal
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.dtype
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.log
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.ndim
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.norm
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.rsqrt
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.shape

李响

• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.storage_offset
• https://oneflow.readthedocs.io/en/master/oneflow.html#oneflow.argsort

王迎港

• https://oneflow.readthedocs.io/en/master/autograd.html#oneflow.autograd.grad
• https://oneflow.readthedocs.io/en/master/autograd.html#oneflow.autograd.backward
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.grad
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.grad_fn
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.is_lazy
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.is_leaf
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.requires_grad
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.register_hook
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.requires_grad_
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.retain_grad

韩彬彬

• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.is_global
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.placement
• https://oneflow.readthedocs.io/en/master/oneflow.html#oneflow.to
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.device

赵露阳

• https://oneflow.readthedocs.io/en/master/functional.html#oneflow.nn.functional.layer_norm
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.zeros_
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.is_contiguous
• https://oneflow.readthedocs.io/en/master/tensor.html#oneflow.Tensor.is_cuda

郑泽康

• https://oneflow.readthedocs.io/en/master/optim.html#oneflow.optim.AdamW.support_sparse
• https://oneflow.readthedocs.io/en/master/optim.html#oneflow.optim.Optimizer.step
• https://oneflow.readthedocs.io/en/master/optim.html#oneflow.optim.Optimizer.support_sparse
• https://oneflow.readthedocs.io/en/master/optim.html#oneflow.optim.SGD.step
• https://oneflow.readthedocs.io/en/master/optim.html#oneflow.optim.SGD.support_sparse
• https://oneflow.readthedocs.io/en/master/optim.html#oneflow.optim.lr_scheduler.LambdaLR.step
• https://oneflow.readthedocs.io/en/master/optim.html#oneflow.optim.lr_scheduler.ReduceLROnPlateau.in_cooldown
• https://oneflow.readthedocs.io/en/master/optim.html#oneflow.optim.lr_scheduler.ReduceLROnPlateau.is_better
• https://oneflow.readthedocs.io/en/master/nn.html#oneflow.nn.FusedMLP

张文骁

• https://oneflow.readthedocs.io/en/master/nn.html#oneflow.nn.CropMirrorNormalize
• https://oneflow.readthedocs.io/en/master/nn.html#oneflow.nn.OFRecordImageDecoder
• https://oneflow.readthedocs.io/en/master/nn.html#oneflow.nn.OFRecordImageDecoderRandomCrop
• https://oneflow.readthedocs.io/en/master/nn.html#oneflow.nn.OFRecordRawDecoder
• https://oneflow.readthedocs.io/en/master/nn.html#oneflow.nn.OFRecordReader

郭冉

• https://oneflow.readthedocs.io/en/master/nn.html#oneflow.nn.COCOReader
• https://oneflow.readthedocs.io/en/master/nn.html#oneflow.nn.CoinFlip

许啸宇

• https://oneflow.readthedocs.io/en/master/nn.html#oneflow.nn.Parameter
• https://oneflow.readthedocs.io/en/master/nn.html#oneflow.nn.ParameterDict
• https://oneflow.readthedocs.io/en/master/nn.html#oneflow.nn.ParameterList
• https://oneflow.readthedocs.io/en/master/nn.html#oneflow.nn.parallel.DistributedDataParallel

张逸清

• https://oneflow.readthedocs.io/en/master/nn.html#oneflow.nn.ModuleDict
• https://oneflow.readthedocs.io/en/master/nn.html#oneflow.nn.ModuleList
• https://oneflow.readthedocs.io/en/master/nn.html#oneflow.nn.MovingAverageMinMaxObserver.reset_running_stats
• https://oneflow.readthedocs.io/en/master/module.html?highlight=nn.Module#oneflow.nn.Module

以下 reset_parametes 不应该导出，其实是需要修改 sphinx 配置。

• https://oneflow.readthedocs.io/en/master/nn.html#oneflow.nn.Linear.reset_parametes
• https://oneflow.readthedocs.io/en/master/nn.html#oneflow.nn.GroupNorm.reset_parametes

[rainyq69]

• fix signature problems of API docstring of some methods oneflow#7834