[Docs] 中文文档部分 API 文件在大小写不敏感的文件系统下的相互覆盖问题

[SigureMo]

文档链接&描述 Document Links & Description

部分 API 是除大小写外完全一样的，目前已知的 API 主要有以下 6 个：

• paddle.vision.transforms.Normalize 和 paddle.vision.transforms.normalize
• paddle.vision.transforms.Pad 和 paddle.vision.transforms.pad
• paddle.vision.transforms.Resize 和 paddle.vision.transforms.resize
• paddle.vision.models.AlexNet 和 paddle.vision.transforms.alexnet
• paddle.vision.models.GoogLeNet 和 paddle.vision.models.googlenet
• paddle.metric.Accuracy 和 paddle.metric.accuracy

这里以 Normalize API 为例，由于目前中文文档的源文件要求文件路径是与 API 路径一致，因此 Normalize API 文档源文件和 normalize API 文档源文件是在同一个目录下的 Normalize_cn.rst 和 normalize_cn.rst，因此这两个文件在大小写不敏感的文件系统下是视为同一个文件的。而恰恰大多数主流文件系统的默认行为都是大小写不敏感，比如 Windows 的 NTFS 和 macOS 的 APFS。

这就导致了 git 在大小写不敏感系统下会认为这些文件发生了改动，比如这是我个人在 macOS（APFS，大小写不敏感）上的 docs 项目，刚刚 clone 下来的状态，git status 状态如下：

~/Projects/paddle-docs develop*
❯ git status
位于分支 develop
您的分支与上游分支 'origin/develop' 一致。

尚未暂存以备提交的变更：
  （使用 "git add <文件>..." 更新要提交的内容）
  （使用 "git restore <文件>..." 丢弃工作区的改动）
        修改：     docs/api/paddle/vision/models/AlexNet_cn.rst
        修改：     docs/api/paddle/vision/models/GoogLeNet_cn.rst
        修改：     docs/api/paddle/vision/transforms/Normalize_cn.rst

修改尚未加入提交（使用 "git add" 和/或 "git commit -a"）

在没有做出任何改动的情况下仍然显示有 3 个文件 change 了（由于另外两个 API 现在因为某次误操作修改成同样的内容，因此仅显示 3 个，「正常」情况下是一直显示 6 个的）

由于 git 认为这是改动，因此一些不太了解的同学或者一些同学在不注意的情况下就 git add -A 之后全部 commit 了，最终结果就是这些 API 文档变成了相同的内容。这种情况已经发生了不止一次（经常是一些全量修复，review 时也是很难检查出来的），相关的修复也已经不止一次了（如 PaddlePaddle/docs#4818 和 PaddlePaddle/docs#5076 ）

导致的问题不止这一个，每当 upstream 对这 6 个文件进行任何微小的 change 时，我个人这边就无法同步 upstream 的 change，只能重新 clone……体验上也是非常不佳……

为了避免相关问题，我个人在做相关贡献时，都是使用 GitHub 提供的 codespace（Linux，ext4 文件系统，默认大小写敏感），但毕竟是远程环境，每次开发前需要额外做一点点的环境配置……

但我们不能强求所有开发者都使用大小写敏感的文件系统进行开发，比如我宁愿使用 codespace 作为远程开发环境也不愿新建一个大小写敏感的 APFS 分区用来开发，而且问题仅仅发生在 PaddlePaddle/docs 这一个项目，我个人认为没有必要去为此去重建分区

因此希望允许中文文档部分 API 源文件名与 API 路径不一致，比如 normalize API 对应文件名为 normalize[lowercase]_cn.rst（只是随便一个例子，目前文件名并没有太好的建议），并通过配置建立 normalize[lowercase]_cn.rst -> normalize 这个 API 的映射

请提出你的建议 Please give your suggestion

同上最后的建议，建立一个文件名到 API 的映射

最简单的解决方案是源码管理上使用 normalize[lowercase]_cn.rst，在构建阶段之前 mv normalize[lowercase]_cn.rst normalize_cn.rst，这是最简单的解决方案，虽然并不能从根本解决问题（比如有人想在大小写不敏感的文件系统上本地构建文档），但这是一个最简洁有效的解决方案，应当在 Paddle docs 的构建脚本 gen_doc.py 开始部分加上相关逻辑即可

此外就是从 Sphinx 的构建流程上修改默认的映射关系，这可能需要对 Sphinx 进行配置或者写一个 Sphinx 扩展……

[paddle-bot]

您好，我们已经收到了您的问题，会安排技术人员尽快解答您的问题，请耐心等待。请您再次检查是否提供了清晰的问题描述、复现代码、环境&版本、报错信息等。同时，您也可以通过查看官网API文档、常见问题、历史Issue、AI社区来寻求解答。祝您生活愉快～

Hi! We've received your issue and please be patient to get responded. We will arrange technicians to answer your questions as soon as possible. Please make sure that you have posted enough message to demo your request. You may also check out the API，FAQ，Github Issue and AI community to get the answer.Have a nice day!

[Ligoml]

@jeff41404 @Shaun2016 @jzhang533 是一个长期困扰开发者的问题，希望有办法解决~

[Ligoml]

这个问题应该会被 PaddlePaddle/docs#5174 解决，可以后续再观察一下~

[SigureMo]

这个问题应该会被 PaddlePaddle/docs#5174 解决，可以后续再观察一下~

嗯嗯，按理说是可以被 PaddlePaddle/docs#5174 解决的，不过目前我看只是 rename 了，还没处理映射关系，所以那个预览看起来是这样的：

develop 是正常的，可能还没更新？

等完全解决后我 close 本 issue

[dingjiaweiww]

你看的是测试环境，修改文件名的pr已经上线到正式环境了，官网develop版本现在已经修改正确，2.2/2.3 版本今天会merge pr，晚间官网自动更新，明天可以再check下2.2/2.3 的官网文档，多谢反馈

[SigureMo]

develop 是正常的，可能还没更新？

嗯，我确定了下 develop 分支不是没更新，所以这个修复确实是有效的