-
Notifications
You must be signed in to change notification settings - Fork 5.2k
Labels
DocThis PR/issue related with documentsThis PR/issue related with documents
Description
NOTE:这是一个用于长期 Tracking Feature 的 issue,所以在相关工作完成之前,请不要关闭。
Describe problem solved by the proposed feature
需求来源:
- 见 [Feature] RTT 文档优化 #9871 中的 ”问题 1“
- 2025 RT-Thread 全球技术大会演讲:
B 站视频回放:RT-Thread 内核仓库文档改进工作介绍_汪辰,slides
这个 issue 用于搜集 RTT 代码仓库中和 doxygen 文档维护改进相关的 issue,相关工作可以分为下面几大部分:
-
(1)基础框架和支持工作
- [Feature] 初始的统一 doxgen 框架 #9880 resolved by doxygen: create framework to unify markdown and source code part #9946
- [Feature] provde guide on how to add doxygen style comment for API #9970 resolved by doxygen: add documentation for doxygen #9975
- doxygen: add prefix for page name #9989
- doxygen: add prefix for groups #9991
- [doc]Add recommanded script and extension for writing doxygen comments on … #10001
- doxygen: More strict checks on build results #10007
- doxygen: Improve the text description of the introduction section #10015
- doxygen: support running from the root directory #10016
- doxygen: reorganize directory structure #10026
- doxygen: group examples in subpages #10082
- doxygen: cleanup and re-org files #10183
- doxygen: re-org module groups #10197
- doxygen: use layout to control the html display #10408
-
(2)API 的 group 组织整理,缺的需要补上。(issue 还没有提,待定 TBD)
-
(3)特定 group 的 API 的 doxygen 注释。依赖于 (1)和 (2)
- [doxygen] add doxygen comment for clk.c and clk.h #9950
- doxygen: finsh: Normalize macro definitions #10006
- [Feature] lwp, dm 等组件需要补充 doxygen 注释 | Add Doxygen Comments for Components #9263
- [Feature] [doc] doxygen文档中缺少driver相关的doxygen #9424
- doxygen: Improve the text description of the introduction section #10015
- [RFC][doxygen]Doxygen comment standard processing #10058 pr 的标题迷惑,实际是针对 driver 的 audio 模块的文档优化
- doxygen: improve doc for kernel basics section #10066
- doxygen: update doc for kenrel object model #10104
- 其他具体条目有待进一步收集,issue 待整理和提交。
- 看 https://www.rt-thread.org/document/site/#/rt-thread-version/rt-thread-smart/introduction/rt-smart-lwp/rt-smart-lwp 中提到 “RT-Thread 用户态版本 API 和原系统 API 的差异" 的问题,是说 RTT 支持 smart 后,对于原先 RTT 提供的 API,用户态程序还可以有一部分可以直接调用,如果在 RTT 上有一部分可以直接调用,那怎么区分?用户编程时怎么知道哪些 API 是可以直接调用的?习惯上我理解用户态的程序,只能通过 system call 和内核交互的吧,直接调用内核提供的 api 感觉有点怪怪的。
-
(4)Markdown 文档中涉及 API 的描述部分应尽可能复用 source 源代码中的 doxygen comment 描述,避免在 markdown 文档中重复再写一份。这部分工作依赖于 (3)并且需要分解为小的 issue 来 track(TBD)。
-
(5)此外,我建议在 doxygen 整理这项工作开展的同时 (即 (2)和 (3)),我建议也同步开展 utest 的整理工作。具体来说,就是每梳理一个模块(对应 doxygen 中的一个 group),同时整理这个 group 对应的 utest。也就是说下面这两项工作会同步协调开展。有关 utest 的讨论,参考 [Feature] 改进自动化测试以及 ci 看护 #9775
-
(6) 其他相关改进
Describe your preferred solution
No response
Describe possible alternatives
No response
Sub-issues
Collapse Sub-issuesSub-issues
- Manage this item control⌃ shift⇧ uU
To pick up a draggable item, press the space bar.
While dragging, use the arrow keys to move the item.
Press space again to drop the item in its new position, or press escape to cancel.
Metadata
Metadata
Assignees
Labels
DocThis PR/issue related with documentsThis PR/issue related with documents
Type
Projects
Milestone
Relationships
Development
Select code repository
Activity
unicornx commentedon Dec 24, 2024
有关文档改进的工作我也很有兴趣,希望能在相关方面做些工作,推进一下。
BernardXiong commentedon Dec 24, 2024
文档中心
BernardXiong commentedon Dec 24, 2024
英文documentation的部署是在这里: https://www.rt-thread.io/document/site/
不清楚是否是机器人自动化部署的了,可能不是。
supperthomas commentedon Dec 24, 2024
这个doxygen还有很多未更新的地方,汪老师可以PR维护一下。
unicornx commentedon Dec 24, 2024
谢谢补充,我更新到 issue 的 问题 2 中了
unicornx commentedon Dec 27, 2024
Modules 的层次结构设计
是否可以和 documentation 下的文档结合起来,结构的安排尽量和其对齐。
就是有没有可能将下面两个网站的内容统一起来?
unicornx commentedon Jan 3, 2025
@supperthomas 这个 issue 列举了很多其他的问题,不是单个 #9859 就完全解决的,所以重新打开
11 remaining items