Description
Describe problem solved by the proposed feature
问题 1:我感觉 RTT 的文档管理分布有点散,目前可以看到存在这么几处无关联的文档中心:
- RTT 文档中心 https://www.rt-thread.org/document/site/#/ 内核介绍手册,中文的,分成 标准版本/Nano版本/smart 版本/开发工具,具体内容维护在 https://gitee.com/rtthread/docs-online。
- RTT git 仓库源码下的 documentation 目录下(不包括
documentation/doxygen
)的 markdown 文件,英文版本,部署在 https://www.rt-thread.io/document/site/,但是否有和 RTT master 同步,以及是谁维护还不清楚。感觉像是和 RTT 中文文档中心的 “标准版本” 部分有对应关系。谁先谁后,谁翻译的谁?两边有同步吗? - RTT git 仓库源码下的 doxygen 管理的 API 部分 (
documentation/doxygen
),还对应一个年久失修的 https://www.rt-thread.org/document/api/。 最新更新,[doc] doxygen attach github pages #9859 合入后,最新的发布在 http://rt-thread.github.io/rt-thread。 - 我不清楚是否网上是否还有其他和文档有关的部分,感觉还有但是想不起来了
以上列举的这些文档过于分散,有些内容又有重合,我觉得有必要整合起来。我的建议是全部使用 doxygen 管理起来,放在 RTT git 仓库源码下的 documentation 目录下集中维护,包括了内核文档和 API 部分,以及中文和英文一起。完成整合后可以方便地通过 doxygen 技术转化成 html 格式,统一放一份在 internet 的 RTT 官网文档中心上(文档中心以后只要保持和代码仓库的 doxygen 同步即可)。
目前 RTT 仓库下 documentation 下包括了 markdown 形式 和 doxygen 生成 html 两部分工作,研究后觉得可以统一成 doxygen。将 markdown 和 API 部分整合起来,这样英文版本部分,一个 doxygen 搞定,以后部署到互联网上也是一个网址,而不是像现在这样存在两个网址维护。以上是形式上,在内容上,我觉得也有必要将现有 markdown 部分和 代码中的 文档整合起来,这个可以参考 RTEMS 的文档 https://docs.rtems.org/docs/main/c-user.html API 的介绍应该可以加上一些背景介绍(markdown 部分)就更好了,RTEMS 的 API 文档就是类似组织的,每个模块都会包括:
- Introduction : overview 介绍以及该组件 API 的列表
- Background:介绍该组件模块的知识背景
- Operations:介绍 API 的使用案例
- Directives:具体的 API 描述
基于以上想法,我做了一个简单的 draft demo,参考 https://github.com/unicornx/rt-thread/tree/demo-doxygen,安装 doxygen 后运行 documentation/run.sh
就能生成 html 并运行 python http server,打开浏览器访问 8000 端口即可查看网页效果。
中英文统一维护的好处是可以确保以后对文档的改动可以同步改动,每个 PR 检查中文和英文都要改。一个可参考的例子是
https://github.com/torvalds/linux/tree/master/Documentation/translations 或者 https://github.com/sophgo/sophgo-doc/tree/main/SG200X/TRM。目前gitee 的文档中心中部分 API 内容和 RTT 仓库的 documentation 下的 markdown 英文感觉就是翻译的关系。放在一起维护会比较好。至于具体放在哪里 (gitee or github)还有待商榷。
问题 2:RTT 文档的组织方式改进问题
RTT 文档中心 https://www.rt-thread.org/document/site/#/ 的组织方式建议改进,可以参考 RTEMS 的文档组织:
https://docs.rtems.org/docs/main/
不用全部都做,但我觉得需要重点先完善的包括:
- "Kenerl API guide",即现在 markdown 部分 + doxygen API 部分,同时补充支持 smart 后新增的 kernel API,用于 driver / bsp 开发。
- "Kernel mode POSIX API guide",对 "Kenerl API guide" 的补充, 仅对 RTT standard 有效, 用于移植 kernel mode 的 application
- "User mode POSIX API guide",针对 smart, 用于移植 user mode 的 application
- ”RT-Thread User Manual" 涉及 RTT 的安装,工具使用等等说明,对标 RTEMS User Manual。
Describe your preferred solution
No response
Describe possible alternatives
No response