飞桨 API 文档中的前端问题汇总

[BrilliantYuKaimin]

飞桨文档评估工作小组在工作时发现了大量需要由前端工程师才能解决的问题，本 issue 将作为这些问题的汇总。大家在报告问题时请尽可能详细地附上问题示例。

[SigureMo]

问题发生区域

• 英文文档
• 中文文档

问题详情

原 PaddlePaddle/docs#4935 ，现已 close

除大小写外同名 API 在侧边栏排序不稳定

打开 API 文档 paddle.vision.models 页面，观察 alexnet 和 AlexNet 以及 googlenet 和 GoogLeNet，随意点击侧边栏进行跳转，可以发现 alexnet 和 AlexNet 的相对位置（googlenet 那俩一样）是不稳定的，经常调换，因此猜测前端 sidebar 运行时排序没有考虑除大小写外同名的情况

当然，Resize、resize 等等这些同名的 API 也会有这样的问题。虽然不会有太大影响，但稍微有点影响用户体验。

示例链接及截图

https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/vision/models/AlexNet_cn.html

Screen-2022-06-16-165415.mp4

[BrilliantYuKaimin]

公式编号问题

据观察，飞桨文档中的数学公式是由 MathJax 渲染的，而 MathJax 对于 equation 环境下的公式是可以自动编号的。经测试（ PaddlePaddle/docs#4955 ），飞桨文档中没有自动启用公式编号的功能。希望前端工程师对这个功能予以支持。提出这个需求是因为引用公式会使有些参数的解释更加简单、明确，如：

[Ligoml]

英文文档问题

前端关键字渲染问题

• Return 与 Return type 的问题：对英文API文档，会将源码中 returns 的值渲染为这两部分，冒号前是 Return，冒号后是 Return type，这一方面导致了中英文文档的不一致（中文文档是纯rst），另一方面也使阅读英文文档体验稍差，建议统一一下，可以选择 a)去掉这种渲染形式；b)为所有中文文档增加 Return type。建议方案a
• 关键字值为 None 时的逻辑错误：参考示例：paddle.get_cuda_rng_state 因为特殊样式的渲染，当值为 None 时，会将 None 当做参数，然后在后面增加一个连接符 -，很奇怪，建议增加：值为 None 时的逻辑判断
• shape 样式缺失：官网对API英文文档中的关键字：如 args、examples 会触发特定的样式，但是 shape 似乎没有加入，导致 nn 下的class 类 API 在文档写作中会遇到一些尴尬，参考示例：paddle.nn.AdaptiveAvgPool1D
  args 与 shape 在源码中的写法是一致的，但实际效果有差距，如果要在格式上保持一致，可以选择 a)在源码中修改；b)为shape增加特殊样式。建议方案b

关键字目录层级不明确的问题

@SigureMo 已经在上文说的比较清楚了，建议修改

超链接失效的问题（红线）

中文文档使用标签互相索引，问题不大，英文文档索引方式不明确，大部分索引都是失效状态，如 broadcast、inplace API等，都没有被有效索引起来。TODO：增加英文文档互相索引的文档

前端错误（红线）

with_quant_attr (BOOLEAN) 多个API文档中都出现了这个多余的参数，参考示例：paddle.multiply、paddle.floor

特殊 API 均存在上述问题

API名称渲染问题

多出来一个空格，参考样例：paddle.static.Print

[enkilee]

https://www.paddlepaddle.org.cn/documentation/docs/en/develop/api/paddle/profiler/Profiler_en.html
文档中，例子1和2的代码颜色高亮正确，代码3就不正确了。

查看前段，是CSS的问题，但估计是应该是解释器的问题了。
例子2的css:

例子3的css:

可是在文档中，2段代码的开头解释是一样的：

[enkilee]

中英文文档前端显示的问题：
英文文档，类里面显示了方法的使用，中文没有，但是py文件里没有文档说明，想在方法前面加一行 Methods， 告诉读者这后面是类里面的方法。

[paddle-bot]

Since you haven't replied for more than a year, we have closed this issue/pr.
If the problem is not solved or there is a follow-up one, please reopen it at any time and we will continue to follow up.
由于您超过一年未回复，我们将关闭这个issue/pr。
若问题未解决或有后续问题，请随时重新打开，我们会继续跟进。