docs: Add a new document site

[SWHL]

问题描述

现有仓库下文档散落在各个目录下，不利于小伙伴查找和使用。

解决方案

采用mkdocs-material + Github Pages搭建更加现在化文档站点。

特色

• 支持中英文搜索，更加快速找打自己所需
• 文档支持中英两种语言，当然也可以支持更多语言，欢迎有意向翻译的小伙伴，戳这里
• 文档带有评论系统，可以基于某篇文档，提出自己疑问、看法等
• 更多特色，静待自己去挖掘

[GreatV]

换一个有意义的名字吧

[SWHL]

可以的

[GreatV]

我们没有 master 分支

[SWHL]

有main分支就好了，这是mkdocs-material官方给的模板，不影响使用

[GreatV]

这里每个文件都要改造一下，感觉不太好。

[SWHL]

因为采用了mkdocs-materail模板，必然要遵循它的结构。我没觉得哪里不太好。

[jzhang533]

这个不用注释掉的，只是会在本地进行拦截， github action 流水线里不会拦截。
可以在本地提交前临时关闭 pre-commit 来提交。

[SWHL]

ok，一会我改一下

[jzhang533]

还是需要再看看，在调整目录结构的时候，如何能保留原始的文档的 commit log， 这样未来维护这些文档的时候，可以查看 git log 来看看历史上改动文档的原因。
曾经另一个重要的文档仓库 Docs ，在调整目录结构时，丢失了 fluid 时代的 commit log， 导致后来维护文档的时候无法追溯。

[SWHL]

嗯嗯，你们慢慢看，我就先不搞这里了

[jzhang533]

我又仔细看了一下新的文档结构，以及跟以前的做了一下对比。
在现在的基础上，强求保留原来的文档的 commit log 的话，会是比较耗时（可能也没有那么大的必要）的工作，所以比较倾向于往前推进把这个 PR 合入，然后尽快让 PaddleOCR 的文档站点上线。

我想到的的事情还有这些

• 我们需要确定一个域名，比如是不是： https://paddlepaddle.github.io/PaddleOCR 这个域名会比较合适。启用这个域名的话，看起来是需要创建一个新的代码仓库 paddlepaddle.github.io ？ 如果是的话，我来走内部流程开通这个代码仓库。
• 对于原来存放在代码仓库的其他地方的文档的维护，新的文档目录(docs)，里的文档来自于下面四个目录
  • ./doc 目录： 这个是 ppocr 的文档目录，我不确定是否都已经搬运完毕，如果已经完成的话，我倾向于把这个目录删除，以避免，未来错误的把文档存放到了 ./doc 目录。
  • ./ppstructure/docs 目录：同上，这个是 ppstructure 的文档目录。我也倾向于把这里的文档全部搬迁后，整体删除。
  • ./applications 目录：看起来是都已经搬迁完成，这个目录应该可以直接删除了。
  • ./deploy 目录：这个目录里同样是不只有文档，也有代码，但这些代码，应该被当做是怎么样使用推理工具的示例代码，所以我也建议整个 deploy 目录逐步的进行清理，然后把这里的示例的代码也搬迁至 docs 目录下。

我基本是用这个脚本来对比看做了哪些调整的： explore_docs_structure.sh
P.S. ： 这四个目录的清理工作，可以等这个 PR 合入后，作为 TODO 来开展，来提升项目的可维护性。

• 新的 docs 的结构
  • docs/ppocr/blog 和 docs/ppstructure/blog，这两个地方的 blog 是不是可以合并起来，挪到 docs 的根目录下？
  • 如果未来还有机会继续调整文档结构的话，可以参考这个：The Documentation System， TVM Doc。
• 其他小事情
  • 看起来是有些文档被设置成了，是可执行的权限，如 docs/ppocr/infer_deploy/benchmark.en.md ，可以统一取消可执行权限。
  • README.md 的第 74 行的图片，竟然是意外的放在 @tink2123 的个人的 test 仓库里，好有趣。

也请大家也发表一下看法： @GreatV @tink2123 @mattheliu

[mattheliu]

看法：
感觉paddlepaddle.github.io/PaddleOCR，PaddleOCR-docs.github.io都OK的
支持bolg挪到docs根目录
疑问：
是打算将 ./deploy 下的代码文件全部搬迁到docs 目录下嘛

[SWHL]

我们需要确定一个域名，比如是不是： https://paddlepaddle.github.io/PaddleOCR 这个域名会比较合适。启用这个域名的话，看起来是需要创建一个新的代码仓库 paddlepaddle.github.io ？ 如果是的话，我来走内部流程开通这个代码仓库。

A: https://paddlepaddle.github.io/PaddleOCRDocs/ 这个域名是Github Pages部署成功后，默认的。不需要额外做什么？

---

./doc 目录： 这个是 ppocr 的文档目录，我不确定是否都已经搬运完毕，如果已经完成的话，我倾向于把这个目录删除，以避免，未来错误的把文档存放到了 ./doc 目录。

A: 这个后期是有打算逐步删除的，因为文档众多，我也不确定是否有遗漏，想着先上线，再慢慢来看问题

---

./deploy 目录：这个目录里同样是不只有文档，也有代码，但这些代码，应该被当做是怎么样使用推理工具的示例代码，所以我也建议整个 deploy 目录逐步的进行清理，然后把这里的示例的代码也搬迁至 docs 目录下。

A: 这个我有点不太明白，deploy代码放到docs目录下，是出于什么样的考虑呢？

---

docs/ppocr/blog 和 docs/ppstructure/blog，这两个地方的 blog 是不是可以合并起来，挪到 docs 的根目录下？

A: 这个之所有有两个blog，是因为ppocr和ppstructure下都有一些属于各自范围下的文章，都合并起来，感觉会有些混乱。

---

如果未来还有机会继续调整文档结构的话，可以参考这个：The Documentation System， TVM Doc。

A: 这个可以的

---

看起来是有些文档被设置成了，是可执行的权限，如 docs/ppocr/infer_deploy/benchmark.en.md ，可以统一取消可执行权限。

A: 这个没有看懂，文档被设置为可执行权限，是指什么？

[jzhang533]

./deploy 目录：这个目录里同样是不只有文档，也有代码，但这些代码，应该被当做是怎么样使用推理工具的示例代码，所以我也建议整个 deploy 目录逐步的进行清理，然后把这里的示例的代码也搬迁至 docs 目录下。

A: 这个我有点不太明白，deploy代码放到docs目录下，是出于什么样的考虑呢？

因为 deploy 下的文件，都是在教学怎么样使用训练出来的模型做推理部署，并没有去实现一个特定的推理库，。即便是有代码，其实也是示例性质的，在演示怎么用其他的工具推理 PaddleOCR 的模型。从这个角度，我觉得应该归类为文档。我只是粗略的看了一下 deploy 这个目录下的文件，也有可能理解不准确。

docs/ppocr/blog 和 docs/ppstructure/blog，这两个地方的 blog 是不是可以合并起来，挪到 docs 的根目录下？

A: 这个之所有有两个blog，是因为ppocr和ppstructure下都有一些属于各自范围下的文章，都合并起来，感觉会有些混乱。

主要是叫 blog（博客）的话，其实是需要定期有帖子发出来的一个博客站点，类似于 pytorch blog，一个开源项目有一个博客看起来比较合理。我刚才又看了看现有的塞到了 blog 下的内容，严格来说更像是技术文章的合集，是不是不叫 blog， 叫 tutorials (实践指南) 或者 articles (文章)，还是分开放在 ppocr 和 ppstructure 下，更加合理一些？

看起来是有些文档被设置成了，是可执行的权限，如 docs/ppocr/infer_deploy/benchmark.en.md ，可以统一取消可执行权限。

A: 这个没有看懂，文档被设置为可执行权限，是指什么？

ls -l docs/ppocr/infer_deploy/benchmark.en.md
-rwxr-xr-x  1 zhangjun25  staff  1730 Jul 22 10:40 docs/ppocr/infer_deploy/benchmark.en.md

第一列是有 x 权限标识的， 只有可执行的文件才需要有这个权限。 当然这个是个小事情了。

[SWHL]

因为 deploy 下的文件，都是在教学怎么样使用训练出来的模型做推理部署，并没有去实现一个特定的推理库，。即便是有代码，其实也是示例性质的，在演示怎么用其他的工具推理 PaddleOCR 的模型。从这个角度，我觉得应该归类为文档。我只是粗略的看了一下 deploy 这个目录下的文件，也有可能理解不准确。

嗯嗯，理解你的意思。现有文档结构下，放到docs目录下倒是也没有问题。我个人认为还是现在这样放到最外层好一些，好找。^-^

主要是叫 blog（博客）的话，其实是需要定期有帖子发出来的一个博客站点，类似于 pytorch blog，一个开源项目有一个博客看起来比较合理。我刚才又看了看现有的塞到了 blog 下的内容，严格来说更像是技术文章的合集，是不是不叫 blog， 叫 tutorials (实践指南) 或者 articles (文章)，还是分开放在 ppocr 和 ppstructure 下，更加合理一些？

现在塞到blog下的文章，都是不太好分类到现有类别下的文档，实在没地方，又想让大家看到，就塞到blog下了。 比较赞同改成Articles，还放在各自目录下。最外层可以增设一个blog，用来发布一些最近动态啥的。

[GreatV]

1. deploy 是一些demo项目，不太好移动，我倾向于先保留着。
2. 把doc都移动到docs里，然后删除掉doc是不是git上会保留移动的记录。
3. 每个文件都有一个

---
comments: true
---

我觉得不太优雅。

[SWHL]

那么请给出一个优雅的方案呗。我觉得还好

[jzhang533]

LGTM