Skip to content

[Feature] RTT 文档优化 #9871

Closed
Closed
@unicornx

Description

@unicornx

Describe problem solved by the proposed feature

问题 1:我感觉 RTT 的文档管理分布有点散,目前可以看到存在这么几处无关联的文档中心:

以上列举的这些文档过于分散,有些内容又有重合,我觉得有必要整合起来。我的建议是全部使用 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/
image
不用全部都做,但我觉得需要重点先完善的包括:

  • "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

Metadata

Metadata

Assignees

Labels

DocThis PR/issue related with documents

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions