doxygen: create framework to unify markdown and source code part (#9946)

* doxygen: adjust documentation directory structure - Rename documentation/doxygen to documentation/0.doxygen and cleanup some unused files. - Add/rename folders for each sub sections, such as 1.introduction/...... Each sub section will be created as a subpage. - Generate initial Doxyfile, this Doxyfile will be used to unify doxygen generated API documents and those markdown files under documentation folder. This patch just add the default Doxyfile generated by running "doxygen -g". It is used as baseline to add more features/configurations. - Rename documentation/README.md to documentation/INDEX.md, and use it as mainpage. - Move 0.doxygen/readme.md to documentation/README.md. * doxygen: update configurations These configurations are from old documentation/doxygen/Doxyfile. Try best to compatible exixting design. * doxygen: add run script Add a script to automatic some operations. Updated the README.md. --------- Signed-off-by: Chen Wang <unicorn_wang@outlook.com> Co-authored-by: Supper Thomas <78900636@qq.com>
2026-05-21 01:24:35 +08:00 · 2025-01-26 11:44:39 +08:00
parent c3e5152c13
commit 40f3b6a569
133 changed files with 1069 additions and 1043 deletions
@@ -50,7 +50,7 @@ jobs:
      - name: generate doxygen html
        shell: bash
        run: |
-          cd documentation/doxygen
+          cd documentation
          doxygen Doxyfile
          cat Doxyfile
          
@@ -58,7 +58,7 @@ jobs:
        id: deployment
        uses: actions/upload-pages-artifact@main # or specific "vX.X.X" version tag for this action
        with:
-          path: documentation/doxygen/html/
+          path: documentation/html/
          
  deploy:
    if: github.event_name == 'push'
@@ -123,7 +123,7 @@ Based on [STM32F103 BluePill](https://github.com/RT-Thread/rt-thread/tree/master
 ## Simulator

 RT-Thread BSP can be compiled directly and downloaded to the corresponding development board for use. In addition, RT-Thread also provides qemu-vexpress-a9 BSP, which can be used without hardware platform. See the getting started guide below for details. Getting Started of QEMU with Env:
-[Windows](documentation/quick-start/quick_start_qemu/quick_start_qemu.md) | [Linux Ubuntu](documentation/quick-start/quick_start_qemu/quick_start_qemu_linux.md) | [Mac OS](documentation/quick-start/quick_start_qemu/quick_start_qemu_macos.md)
+[Windows](documentation/2.quick-start/quick_start_qemu/quick_start_qemu_windows.md) | [Linux Ubuntu](documentation/2.quick-start/quick_start_qemu/quick_start_qemu_linux.md) | [Mac OS](documentation/2.quick-start/quick_start_qemu/quick_start_qemu_macos.md)

 # License

@@ -122,7 +122,7 @@ Basierend auf [STM32F103 BluePill](https://github.com/RT-Thread/rt-thread/tree/m
 ## Simulator

 Das RT-Thread BSP kann direkt kompiliert und zur Verwendung auf das entsprechende Entwicklungsboard heruntergeladen werden. Darüber hinaus bietet RT-Thread auch das qemu-vexpress-a9 BSP, das ohne Hardware-Plattform verwendet werden kann. Weitere Informationen finden Sie in der Anleitung für die ersten Schritte unten.
-[Windows](documentation/quick-start/quick_start_qemu/quick_start_qemu.md) | [Linux Ubuntu](documentation/quick-start/quick_start_qemu/quick_start_qemu_linux.md) | [Mac OS](documentation/quick-start/quick_start_qemu/quick_start_qemu_macos.md)
+[Windows](documentation/2.quick-start/quick_start_qemu/quick_start_qemu_windows.md) | [Linux Ubuntu](documentation/2.quick-start/quick_start_qemu/quick_start_qemu_linux.md) | [Mac OS](documentation/2.quick-start/quick_start_qemu/quick_start_qemu_macos.md)

 # Lizenz

@@ -121,7 +121,7 @@ Basado en [STM32F103 BluePill](https://github.com/RT-Thread/rt-thread/tree/maste

 ## Simulator

-El BSP de RT-Thread puede compilarse directamente y descargarse en la placa de desarrollo correspondiente para su uso. Además, RT-Thread también proporciona el BSP qemu-vexpress-a9, que puede utilizarse sin plataforma de hardware. Consulte la guía de inicio más abajo para más detalles. [Windows](documentation/quick-start/quick_start_qemu/quick_start_qemu.md) | [Linux Ubuntu](documentation/quick-start/quick_start_qemu/quick_start_qemu_linux.md) | [Mac OS](documentation/quick-start/quick_start_qemu/quick_start_qemu_macos.md)
+El BSP de RT-Thread puede compilarse directamente y descargarse en la placa de desarrollo correspondiente para su uso. Además, RT-Thread también proporciona el BSP qemu-vexpress-a9, que puede utilizarse sin plataforma de hardware. Consulte la guía de inicio más abajo para más detalles. [Windows](documentation/2.quick-start/quick_start_qemu/quick_start_qemu_windows.md) | [Linux Ubuntu](documentation/2.quick-start/quick_start_qemu/quick_start_qemu_linux.md) | [Mac OS](documentation/2.quick-start/quick_start_qemu/quick_start_qemu_macos.md)

 # Licencia

@@ -124,9 +124,9 @@ RT-Thread Studio演示：

 RT-Thread BSP可以直接编译并下载到相应的开发板使用。此外，RT-Thread还提供 qemu-vexpress-a9 BSP，无需硬件平台即可使用。有关详细信息，请参阅下面的入门指南。

-[QEMU 入门指南(Windows)](documentation/quick-start/quick_start_qemu/quick_start_qemu.md)
+[QEMU 入门指南(Windows)](documentation/2.quick-start/quick_start_qemu/quick_start_qemu_windows.md)

-[QEMU 入门指南(Ubuntu)](documentation/quick-start/quick_start_qemu/quick_start_qemu_linux.md)
+[QEMU 入门指南(Ubuntu)](documentation/2.quick-start/quick_start_qemu/quick_start_qemu_linux.md)


 ## 文档
@@ -1,8 +1,8 @@
-# RT-Thread Introduction 
+@page introduction Introduction

 As a beginner of Real-time Operating Systems (RTOS), you might be new to RT-Thread. However, with a better understanding of it over time, you will gradually discover the charm of RT-Thread and its advantages over other RTOSs of the same type. RT-Thread is an RTOS. With over 16 years of experience accumulated, along with the rise of the Internet of Things (IoT), it is evolving into a powerful, component-rich IoT operating system.  

-## RT-Thread Overview 
+# RT-Thread Overview

 RT-Thread, short for Real Time-Thread, is an embedded real-time multi-threaded operating system. One of its main purposes is to support multi-tasking. Allowing multiple tasks to run simultaneously does not mean that the processor actually performs multiple tasks at the same time - a processor core can only run one task at a time. Every task is executed quickly, and through the task scheduler which determines the sequence according to priority, the tasks are switched rapidly, giving the illusion that multiple tasks are running at the same time. In the RT-Thread system, tasks are implemented by threads, and scheduled by the task scheduler.

@@ -10,11 +10,11 @@ RT-Thread is mainly written in the C programming language, making it easy to und

 Compared with the Linux operating system, RT-Thread is small in size, low in cost, low in power consumption and fast in startup. In addition, RT-Thread is highly responsible, with low resource usage, which is ideally suitable for various resource constraints such as cost, power consumption, etc. Although the 32-bit MCU is its main operating platform, other CPUs, such as ones with MMU, ones based on ARM9, ARM11 and even the Cortex-A series CPUs are suitable for RT-Thread in specific applications.

-## License Agreement
+# License Agreement

 The RT-Thread system is a completely open source system, which follows the Apache License 2.0 open source license agreement. The RT-Thread system can be used free of charge in commercial products and does not require opening private code up to the public.

-## RT-Thread Frame
+# RT-Thread Frame

 In recent years, the concept of the Internet of Things has become widely known, and the IoT market has developed rapidly. The networking of embedded devices is the trend of the times. Terminal networking has greatly increased the complexity of software, and traditional RTOS kernels can hardly meet the needs of the market. For this reason, the concept of the Internet of Things Operating System (IoT OS) came into being. **IoT operating system refers to the software platform that is based on operating system kernel (like RTOS, Linux, etc.) and includes relatively complete middleware components such as a file system, graphics library, etc. It has low overhead and high security, abides by the Communication Protocol and is capable of connecting to the cloud.** RT-Thread is an IoT OS. 

@@ -1,4 +1,4 @@
-# Keil MDK Installation
+@page quickstart_keil Keil MDK Installation

 Before running the RT-Thread operating system, we need to install MDK-ARM 5.24 (either official or evaluation version, version 5.14 and above), this version is also a relatively new version. This version can provide relatively complete debugging functions. Here, we are using evaluation version 5.24 of 16k compiled code limit. If you want to remove the 16k compiled code limit, please purchase the official MDK-ARM.

@@ -1,4 +1,4 @@
-# Start Guide: Simulate STM32F103 on Keil Simulator
+@page quick_start Start Guide

 Because of its particularity, the embedded operating system is often closely related to the hardware platform, and specific embedded operating systems can only run on specific hardware. For those who might not have an RT-Thread compatible hardware module, or want to test out their ideas, a complete RT-Thread system can be developed in the simulation environment MDK-ARM.

@@ -8,11 +8,11 @@ Because of its full STM32F103 software simulation environment, the MDK-ARM integ

 What will follow is a demonstration of RT-Thread running on a simulated STM32F103 microcontroller through MDK-ARM.

-## Preparation
+# Preparation

-MDK development environment: MDK-ARM 5.24 (official or evaluation version, version 5.14 and above) needs to be installed. This version is a relatively new version, which can provide relatively complete debugging functions. An installation guide can be found here: [Keil MDK Installation](./keil-installation/keil-installation.md).
+MDK development environment: MDK-ARM 5.24 (official or evaluation version, version 5.14 and above) needs to be installed. This version is a relatively new version, which can provide relatively complete debugging functions. An installation guide can be found here: @subpage quickstart_keil.

-## First acquaintance with RT-Thread
+# First acquaintance with RT-Thread

 To see the code size of RT-Thread we first need to get an example of RT-Thread that is suited for this environment, which can be obtained from the following link:

@@ -69,7 +69,7 @@ After compiling RT-Thread/STM32, we can simulate running RT-Thread through the M
 ![simulate RT-Thread2](./figures/6.png)


-## User Entry Code
+# User Entry Code

 The above startup code is related to the RT-Thread system, so how do users add initialization code for their own applications? RT-Thread uses main function as the user code entry, all you need to do is just add your own code to the main function.

@@ -83,7 +83,7 @@ int main(void)

 >Note: In order to complete the initialization for the system functions before entering the main program, you can use the `$sub$$` and `$super$$` function identifiers to call another sample before entering the main program, this was, users can ignore the initialization operations before the main() function. See [ARM® Compiler v5.06 for µVision® armlink User Guide](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0377g/pge1362065967698.html) for details.

-## Example of a Marquee
+# Example of a Marquee

 For technical engineers working on electronics, marquee is probably the simplest example, the equivalent of Hello World in every programming language programmers learn. So we will start with a marquee in the following example, to make it periodically update (turn on or off) the LED.

@@ -123,13 +123,13 @@ int led(void)
 MSH_CMD_EXPORT(led, RT-Thread first led sample);
 ```

-## Other Examples
+# Other Examples

 Additional kernel examples can be found in the kernel-sample-0.1.0 directory.

 ![more kernel samples](./figures/14.png)

-## Frequently Asked Question
+# Frequently Asked Question

 * Compilation error occurred as following:

--- a/Show More
+++ b/Show More