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>

.github/workflows/doxygen.yml

@@ -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'

README.md

@@ -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
 

README_de.md

@@ -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
 

README_es.md

@@ -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
 

README_zh.md

@@ -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)
 
 
 ## 文档

documentation/1.introduction/introduction.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. 
 

documentation/2.quick-start/keil-installation/keil-installation.md

@@ -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.
 

documentation/2.quick-start/quick-start.md

@@ -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:
 

documentation/3.kernel/INDEX.md

@@ -0,0 +1,10 @@
+@page kernel Kenrel
+
+- @subpage kernel_basics
+- @subpage thread_management
+- @subpage clock_management
+- @subpage thread_sync
+- @subpage thread_comm
+- @subpage memory_management
+- @subpage interrupt_management
+- @subpage kernel_porting

documentation/4.tool/INDEX.md

@@ -0,0 +1,5 @@
+@page tool Tool
+
+- @subpage env
+
+- @subpage scons

documentation/5.device/INDEX.md

@@ -0,0 +1,14 @@
+@page device Device
+
+- @subpage device_framework
+- @subpage device_pin
+- @subpage device_uart
+- @subpage device_adc
+- @subpage device_i2c
+- @subpage device_spi
+- @subpage device_pwm
+- @subpage device_rtc
+- @subpage device_hwtimer
+- @subpage device_watchdog
+- @subpage device_wlan
+- @subpage device_sensor

documentation/6.components/INDEX.md

@@ -0,0 +1,12 @@
+@page components Components
+
+- @subpage component_finsh
+- @subpage component_vfs
+- @subpage component_utest
+- @subpage component_dlmodule
+- @subpage component_sal
+- @subpage component_at
+- @subpage component_posix
+- @subpage component_ulog
+- @subpage component_pm
+- @subpage component_network

documentation/7.contribution/INDEX.md

@@ -0,0 +1,9 @@
+@page code_contribution Contribution
+
+# Contribution Guide
+
+We sincerely thank you for your contribution, and welcome to submit the code through GitHub's fork and Pull Request processes. RT-Thread 3.1.0 version and its earlier versions follow the GPL V2 open source license agreement. Versions from the 3.1.0 version onwards follow the Apache License 2.0 open source license agreement.
+
+All the real-time operating system kernel and open source components can be used free of charge for commercial products, there is no potential commercial risk and you will not being request to publish application source.
+
+@subpage rtt_code_style_en

documentation/Doxyfile

@@ -38,7 +38,7 @@ PROJECT_NAME           = "RT-Thread RTOS"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 1.2.0
+PROJECT_NUMBER         =
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
@@ -51,14 +51,14 @@ PROJECT_BRIEF          = "An open source embedded real-time operating system"
 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
 # the logo to the output directory.
 
-PROJECT_LOGO           = ./images/rtthread_logo.png
+PROJECT_LOGO           = ./0.doxygen/images/rtthread_logo.png
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
 # into which the generated documentation will be written. If a relative path is
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = .
+OUTPUT_DIRECTORY       =
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and
@@ -864,13 +864,13 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../../src \
-                         ../../include \
-                         . \
-                         ../../components/finsh \
-                         ../../components/drivers/include/drivers \
-                         ../../components/dfs/dfs_v2/src \
-                         ../../components/dfs/dfs_v2/include
+INPUT                  = . \
+                         ../src \
+                         ../include \
+                         ../components/finsh \
+                         ../components/drivers/include/drivers \
+                         ../components/dfs/dfs_v2/src \
+                         ../components/dfs/dfs_v2/include
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -903,13 +903,14 @@ FILE_PATTERNS          = *.c \
                          *.cc \
                          *.cpp \
                          *.h \
-                         *.inc
+                         *.inc \
+                         *.md
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
 # The default value is: NO.
 
-RECURSIVE              = NO
+RECURSIVE              = YES
 
 # The EXCLUDE tag can be used to specify files and/or directories that should be
 # excluded from the INPUT source files. This way you can easily exclude a
@@ -918,7 +919,11 @@ RECURSIVE              = NO
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = .svn
+EXCLUDE                = ./0.doxygen/mainpage.h \
+                         ./README.md \
+                         ./2.quick-start/quick_start_qemu \
+                         ./env/env-vscode.md \
+                         ./contribution_guide/coding_style_cn.md
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -971,7 +976,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             = ./images
+IMAGE_PATH             = .
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -1643,7 +1648,7 @@ MATHJAX_FORMAT         = HTML-CSS
 # The default value is: https://cdn.jsdelivr.net/npm/mathjax@2.
 # This tag requires that the tag USE_MATHJAX is set to YES.
 
-MATHJAX_RELPATH        = http://www.mathjax.org/mathjax
+MATHJAX_RELPATH        = https://cdn.jsdelivr.net/npm/mathjax@2
 
 # The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax
 # extension names that should be enabled during MathJax rendering. For example
@@ -1776,7 +1781,7 @@ LATEX_OUTPUT           = latex
 # the output language.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
-LATEX_CMD_NAME         = latex
+LATEX_CMD_NAME         =
 
 # The MAKEINDEX_CMD_NAME tag can be used to specify the command name to generate
 # index for LaTeX.
@@ -1880,7 +1885,7 @@ LATEX_EXTRA_FILES      =
 # The default value is: YES.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
-PDF_HYPERLINKS         = NO
+PDF_HYPERLINKS         = YES
 
 # If the USE_PDFLATEX tag is set to YES, doxygen will use the engine as
 # specified with LATEX_CMD_NAME to generate the PDF file directly from the LaTeX
@@ -1890,7 +1895,7 @@ PDF_HYPERLINKS         = NO
 # The default value is: YES.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
-USE_PDFLATEX           = NO
+USE_PDFLATEX           = YES
 
 # If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode
 # command to the generated LaTeX files. This will instruct LaTeX to keep running
@@ -2125,10 +2130,6 @@ DOCBOOK_PROGRAMLISTING = NO
 
 GENERATE_AUTOGEN_DEF   = NO
 
-#---------------------------------------------------------------------------
-# Configuration options related to Sqlite3 output
-#---------------------------------------------------------------------------
-
 #---------------------------------------------------------------------------
 # Configuration options related to the Perl module output
 #---------------------------------------------------------------------------
@@ -2337,7 +2338,7 @@ HIDE_UNDOC_RELATIONS   = YES
 # http://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent
 # Bell Labs. The other options in this section have no effect if this option is
 # set to NO
-# The default value is: NO.
+# The default value is: YES.
 
 HAVE_DOT               = YES
 
@@ -2515,7 +2516,9 @@ DIRECTORY_GRAPH        = YES
 # Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order
 # to make the SVG files visible in IE 9+ (other browsers do not have this
 # requirement).
-# Possible values are: png, jpg, gif, svg, png:gd, png:gd:gd, png:cairo,
+# Possible values are: png, png:cairo, png:cairo:cairo, png:cairo:gd, png:gd,
+# png:gd:gd, jpg, jpg:cairo, jpg:cairo:gd, jpg:gd, jpg:gd:gd, gif, gif:cairo,
+# gif:cairo:gd, gif:gd, gif:gd:gd, svg, png:gd, png:gd:gd, png:cairo,
 # png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus and
 # png:gdiplus:gdiplus.
 # The default value is: png.
@@ -2546,7 +2549,7 @@ DOT_PATH               =
 # command).
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOTFILE_DIRS           = ../doxygen/images
+DOTFILE_DIRS           =
 
 # The MSCFILE_DIRS tag can be used to specify one or more directories that
 # contain msc files that are included in the documentation (see the \mscfile

documentation/INDEX.md

@@ -0,0 +1,52 @@
+@mainpage RT-Thread User Guide
+
+@subpage introduction
+
+@subpage quick_start
+
+@subpage kernel
+
+- @ref kernel_basics
+- @ref thread_management
+- @ref clock_management
+- @ref thread_sync
+- @ref thread_comm
+- @ref memory_management
+- @ref interrupt_management
+- @ref kernel_porting
+
+@subpage tool
+
+- @ref env
+- @ref scons
+
+@subpage device
+
+- @ref device_framework
+- @ref device_pin
+- @ref device_uart
+- @ref device_adc
+- @ref device_i2c
+- @ref device_spi
+- @ref device_pwm
+- @ref device_rtc
+- @ref device_hwtimer
+- @ref device_watchdog
+- @ref device_wlan
+- @ref device_sensor
+
+@subpage components
+
+- @ref component_finsh
+- @ref component_vfs
+- @ref component_utest
+- @ref component_dlmodule
+- @ref component_sal
+- @ref component_at
+- @ref component_posix
+- @ref component_ulog
+- @ref component_pm
+- @ref component_network
+
+@subpage code_contribution
+

documentation/README.md

@@ -1,49 +1,55 @@
-# Manual Catalogue
+# How to build doxygen html
 
-- [RT-Thread Introduction](introduction/introduction.md)
-- [Start Guide: Simulate STM32F103 on KEIL simulator](quick-start/quick-start.md)
+1. download from https://doxygen.nl/index.html
+2. open `Doxywizard`
+3. `File` -> `Open`
+4. Open the file ./Doxyfile 
+5.  To tab `Run` , Click `Run doxygen`
 
-**Kernel**
+# How to build & run doxygen html on Ubuntu
 
-- [Kernel Basics](basic/basic.md)
-- [Thread Management](thread/thread.md)
-- [Clock&Timer Management](timer/timer.md)
-- [Inter-thread Synchronization](thread-sync/thread-sync.md)
-- [Inter-thread Communication](thread-comm/thread-comm.md)
-- [Memory Management](memory/memory.md)
-- [Interrupt Management](interrupt/interrupt.md)
-- [Kernel Porting](kernel-porting/kernel-porting.md)
+The following steps are verified on Ubuntu 22.04：
 
-**Tool**
+```shell
+$ lsb_release -a
+No LSB modules are available.
+Distributor ID:	Ubuntu
+Description:	Ubuntu 22.04.5 LTS
+Release:	22.04
+Codename:	jammy
+```
 
-- [User Manual of Env](env/env.md)
-- [SCons](scons/scons.md)
+The following packages (and dependents) need to be installed:
 
-**Device**
+```shell
+$ sudo apt update
+$ sudo apt install doxygen
+$ sudo apt install graphviz
+```
 
-- [I/O Device Framework](device/device.md)
-- [PIN Device](device/pin/pin.md)
-- [UART Device](device/uart/uart.md)
-- [ADC Device](device/adc/adc.md)
-- [I2C Bus Device](device/i2c/i2c.md)
-- [SPI Device](device/spi/spi.md)
-- [PWM Device](device/pwm/pwm.md)
-- [RTC Device](device/rtc/rtc.md)
-- [HWTIMER Device](device/hwtimer/hwtimer.md)
-- [WATCHDOG Device](device/watchdog/watchdog.md)
-- [WLAN Device](device/wlan/wlan.md)
-- [Sensor Device](device/sensor/sensor.md)
+Assume that the path of RT-Thead code tree is $RTT, execute the following command to build html.
 
-**Components**
+```shell
+$ cd $RTT/documentation
+$ rm -rf html
+$ doxygen
+```
 
-- [FinSH Console](finsh/finsh.md)
-- [Virtual File System](filesystem/README.md)
-- [utest Framework](utest/utest.md)
-- [Dynamic Module: dlmodule](dlmodule/README.md)
-- [Socket Abstraction Layer: SAL](sal/sal.md)
-- [AT Commands](at/at.md)
-- [POSIX Interface](posix/README.md)
-- [Ulog Log](ulog/ulog.md)
-- [Power Management: PM](pm/pm.md)
-- [Network Framework](network/network.md)
+A new html directory will be created and all the html files will be placed in this directory.
 
+If you want to quickly browse HTML locally (in Ubuntu environment), you can enter the html directory and start a local HTML server through Python.
+
+```shell
+$ cd html
+$ python3 -m http.server
+Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
+```
+
+A bash script `run.sh` is provided to automatic upon operations.
+
+```shell
+$ cd $RTT/documentation
+$ ./run.sh
+```
+
+Then open the browser and enter `http://<IP>:8000/index.html` to access the created html web pages. If it is a local access, then `<IP>` should be replaced by `localhost`. If it is a remote access, then `<IP>` should be replaced by the actual accessible IP address of the machine where HTML is located.

documentation/at/at.md

@@ -1,6 +1,6 @@
-# AT Commands #
+@page component_at AT Commands
 
-## Introduction to AT Commands
+# Introduction to AT Commands
 
 The AT command set was originally a control protocol invented by Dennis Hayes, initially used to control dial-up modems. Later, with the upgrade of network bandwidth, low-speed dial-up modems with very low speed essentially exited the general market, but the AT command set was retained. However, the AT command set lived on when major mobile phone manufacturers jointly developed a set of commands to control the GSM modules of mobile phones. The AT command set evolved on this basis and added the GSM 07.05 standard and the later GSM 07.07 standard to achieve more robust standardization.
 
@@ -32,7 +32,7 @@ Although the AT command set has standardization to a certain degree, the AT comm
 
 In order to facilitate the user to use AT commands which can be easily adapted to different AT modules, RT-Thread provides AT components for AT Device connectivity and data communication. The implementation of the AT components consists of both a client and a server.
 
-## Introduction to AT Components
+# Introduction to AT Components
 
 The AT component is based on the implementation of the `AT Server` and `AT Client` of the RT-Thread system. The component completes the AT command transmission, command format and parameter parsing, command response, response data reception, response data parsing, URC data processing, etc.. 
 
@@ -66,9 +66,9 @@ Overall, the AT component resources are extremely small, making them ideal for u
 - AT Socket: An extension of AT Client function, it uses the AT command set to send and receive as the basis. This is implemented through the standard BSD Socket API, which completes the data sending and receiving function, and enables users to implement complete device networking and data communication through AT commands.
 - Multi-client support: The AT component supports multiple clients running simultaneously.
 
-## AT Server ##
+# AT Server
 
-### AT Server Configuration ###
+## AT Server Configuration ###
 
 When we use the AT Server feature in the AT component, we need to define the following configuration in rtconfig.h:
 
@@ -110,7 +110,7 @@ RT-Thread Components  --->
 
 After the add configuration is complete, you can use the command line to rebuild the project, or use `scons` to compile.
 
-### AT Server Initialization ###
+## AT Server Initialization
 
 After enabling the AT Server in Env, you need to initialize it at startup to enable the AT Server function. If the component has been initialized automatically, no additional initialization is required. Otherwise, you need to call the following function in the initialization task:
 
@@ -121,7 +121,7 @@ The AT Server initialization function, which belongs to the application layer fu
 
 After the AT Server is successfully initialized, the device can be used as an AT Server to connect to an AT Client's serial device for data communication, or use a serial-to-USB conversion tool to connect to a PC, so that the PC-side serial debugging assistant can communicate with the AT Client.
 
-### Add custom AT commands ###
+## Add custom AT commands
 
 At present, the format of the AT command set used by AT devices of different manufacturers does not have a completely uniform standard, so the AT Server in the AT component only supports some basic general AT commands, such as ATE, AT+RST, etc. These commands can only be used to meet the basic operation of the device. If users want to use more functions, they need to implement custom AT Server commands for different AT devices. The AT component provides an AT command addition method similar to the FinSH/msh command addition method, which is convenient for users to implement the required commands.
 
@@ -175,9 +175,9 @@ static at_result_t at_test_query(void)
 AT_CMD_EXPORT("AT+TEST", =<value1>[,<value2>], NULL, at_test_query, NULL, at_test_exec);
 ```
 
-### AT Server APIs
+## AT Server APIs
 
-#### Send Data to the Client (no newline)
+### Send Data to the Client (no newline)
 
 ```c
 void at_server_printf(const char *format, ...);
@@ -190,7 +190,7 @@ This function is used by the AT Server to send fixed-format data to the correspo
 | format | Customize the expression of the input data |
 |   ...  | Input data list, variable parameters |
 
-#### Send Data to the Client (newline)
+### Send Data to the Client (newline)
 
 ```c
 void at_server_printfln(const char *format, ...);
@@ -203,7 +203,7 @@ This function is used by the AT Server to send fixed-format data to the correspo
 | format | Customize the expression of the input data |
 |   ...  | Input data list, variable parameters |
 
-#### Send Command Execution Results to the Client
+### Send Command Execution Results to the Client
 
 ```c
 void at_server_print_result(at_result_t result);
@@ -252,7 +252,7 @@ static at_result_t at_test_exec(void)
 AT_CMD_EXPORT("AT+TEST", =<value1>,<value2>, NULL, NULL, at_test_setup, at_test_exec);
 ```
 
-#### Parsing Input Command Parameters
+### Parsing Input Command Parameters
 
 ```c
 int at_req_parse_args(const char *req_args, const char *req_expr, ...);
@@ -299,7 +299,7 @@ static at_result_t at_test_setup(const char *args)
 AT_CMD_EXPORT("AT+TEST", =<value1>,<value2>, NULL, NULL, at_test_setup, NULL);
 ```
 
-#### Porting-related interfaces
+### Porting-related interfaces
 
 The AT Server supports a variety of basic commands (ATE, ATZ, etc.) by default. The function implementation of some commands is related to hardware or platform and requires user-defined implementation. The AT component source code `src/at_server.c` file gives the weak function definition of the migration file. The user can create a new migration file in the project to implement the following function to complete the migration interface, or modify the weak function to complete the migration interface directly in the file.
 
@@ -326,9 +326,9 @@ If you use the gcc toolchain in your project, you need to add the *section* corr
 } > CODE
 ```
 
-## AT Client
+# AT Client
 
-### AT Client Configuration
+## AT Client Configuration
 
 When using the AT Client feature in the AT component, the following configuration in rtconfig.h needs to be defined:
 
@@ -371,7 +371,7 @@ RT-Thread Components  --->
 
 After the configuration is complete, you can use the command line to rebuild the project, or use `scons` to compile.
 
-### AT Client Initialization ###
+## AT Client Initialization
 
 After configuring the AT Client, you need to initialize it at startup to enable the AT Client function. If the component has been initialized automatically, no additional initialization is required. Otherwise, you need to call the following function in the initialization task:
 
@@ -381,7 +381,7 @@ int at_client_init(const char *dev_name,  rt_size_t recv_bufsz);
 
 The AT Client initialization function, which belongs to the application layer function, needs to be called before using the AT Client function or using the AT Client CLI function. The `at_client_init()` function completes the initialization of the AT Client device, the initialization of the AT Client porting function, the semaphore and mutex used by the AT Client, and other resources, and creates the  `at_client` thread for parsing the data received in the AT Client and for processing the URC data.
 
-### AT Client data receiving and sending ###
+## AT Client data receiving and sending
 
 The main function of the AT Client is to send AT commands, receive data, and parse data. The following is an introduction to the processes and APIs related to AT Client data reception and transmission.
 
@@ -418,7 +418,7 @@ In the AT component, this structure is used to define a control block for AT com
 
 Introduction to related API interfaces:
 
-#### Create a Response Structure
+### Create a Response Structure
 
 ```c
 at_response_t at_create_resp(rt_size_t buf_size, rt_size_t line_num, rt_int32_t timeout);
@@ -435,7 +435,7 @@ at_response_t at_create_resp(rt_size_t buf_size, rt_size_t line_num, rt_int32_t
 
 This function is used to create a custom response data receiving structure for later receiving and parsing the send command response data.
 
-#### Delete a Response Structure
+### Delete a Response Structure
 
 ```c
 void at_delete_resp(at_response_t resp);
@@ -447,7 +447,7 @@ void at_delete_resp(at_response_t resp);
 
 This function is used to delete the created response structure object, which is generally paired with the **at_create_resp** creation function.
 
-#### Set the Parameters of Response Structure
+### Set the Parameters of Response Structure
 
 ```c
 at_response_t at_resp_set_info(at_response_t resp, rt_size_t buf_size, rt_size_t line_num, rt_int32_t timeout);
@@ -465,7 +465,7 @@ at_response_t at_resp_set_info(at_response_t resp, rt_size_t buf_size, rt_size_t
 
 This function is used to set the response structure information that has been created. It mainly sets the restriction information on the response data. It is generally used after creating the structure and before sending the AT command. This function is mainly used to send commands when the device is initialized, which can reduce the number of times the response structure is created and reduce the code resource occupation.
 
-#### Send a Command and Receive a Response
+### Send a Command and Receive a Response
 
 ```c
 rt_err_t at_exec_cmd(at_response_t resp, const char *cmd_expr, ...);
@@ -535,11 +535,11 @@ MSH_CMD_EXPORT(at_Client_send, AT Client send commands to AT Server and get resp
 
 The implementation principle of sending and receiving data is relatively simple. It mainly reads and writes the serial port device bound by the AT client, and sets the relevant number of rows and timeout to limit the response data. It is worth noting that the `res` response needs to be created first. The structure passed `in_exec_cmd` function is for data reception. When the `at_exec_cmd` function's parameter `resp` is NULL, it means that the data sent this time **does not consider processing the response data and directly returns the result**.
 
-### AT Client Data Parsing Method ###
+## AT Client Data Parsing Method
 
 After the data is normally acquired, the response data needs to be parsed, which is one of the important functions of the AT Client. Parsing of data in the AT Client provides a parsed form of a custom parsing expression whose parsing syntax uses the standard `sscanf` parsing syntax. Developers can use the custom data parsing expression to respond to useful information in the data, provided that the developer needs to review the relevant manual in advance to understand the basic format of the AT Server device response data that the AT Client connects to. The following is a simple AT Client data parsing method through several functions and routines.
 
-#### Get Response Data for the Specified Line Number
+### Get Response Data for the Specified Line Number
 
 ```c
 const char *at_resp_get_line(at_response_t resp, rt_size_t resp_line);
@@ -555,7 +555,7 @@ const char *at_resp_get_line(at_response_t resp, rt_size_t resp_line);
 
 This function is used to get a row of data with the specified line number in the AT Server response data. The line number is judged by the standard data terminator. The above send and receive functions `at_exec_cmd` have recorded and processed the data and line numbers of the response data in the `resp` response structure, where the data information of the corresponding line number can be directly obtained.
 
-#### Get Response Data by the Specified Keyword
+### Get Response Data by the Specified Keyword
 
 ```c
 const char *at_resp_get_line_by_kw(at_response_t resp, const char *keyword);
@@ -571,7 +571,7 @@ const char *at_resp_get_line_by_kw(at_response_t resp, const char *keyword);
 
 This function is used to get a corresponding row of data by keyword in the AT Server response data.
 
-#### Parse Response Data for the Specified Line Number
+### Parse Response Data for the Specified Line Number
 
 ```c
 int at_resp_parse_line_args(at_response_t resp, rt_size_t resp_line, const char *resp_expr, ...);
@@ -590,7 +590,7 @@ int at_resp_parse_line_args(at_response_t resp, rt_size_t resp_line, const char
 
 This function is used to get a row of data with the specified line number in the AT Server response data, and parse the parameters in the row data.
 
-#### Parse Response Data for a Row with Specified Keyword
+### Parse Response Data for a Row with Specified Keyword
 
 ```c
 int at_resp_parse_line_args_by_kw(at_response_t resp, const char *keyword, const char *resp_expr, ...);
@@ -611,7 +611,7 @@ This function is used to get a row of data containing a keyword in the AT Server
 
 The data parsing syntax uses the standard `sscanf` syntax, the content of the syntax is more, developers can search their parsing syntax, here two procedures are used to introduce the simple use method.
 
-#### Serial Port Configuration Information Analysis Example
+### Serial Port Configuration Information Analysis Example
 
 The data sent by the client:
 
@@ -644,7 +644,7 @@ printf("baudrate=%d, databits=%d, stopbits=%d, parity=%d, control=%d\n",
 at_delete_resp(resp);
 ```
 
-#### IP and MAC Address Resolution Example ####
+### IP and MAC Address Resolution Example
 
 The data sent by the client:
 
@@ -678,7 +678,7 @@ at_delete_resp(resp);
 
 The key to parsing data is to correctly define the expression. Because the response data of the different device manufacturers is not unique to the response data of the AT device, only the form of the custom parsing expression can be obtained to obtain the required information. The design of the `at_resp_parse_line_args` parsing parameter function is based on the `sscanf` data parsing method. Before using it, the developer needs to understand the basic parsing syntax and then design the appropriate parsing syntax in combination with the response data. If the developer does not need to parse the specific parameters, you can use the `at_resp_get_line` function to get the specific data of a row.
 
-### AT Client URC Data Processing ###
+## AT Client URC Data Processing
 
 The processing of URC data is another important feature of AT Client. URC data is the data that is actively sent by the server. It cannot be received by the above data sending and receiving functions. The URC data format and function are different for different devices. Therefore, the URC data processing mode needs to be customized. The AT component provides a list management method for the processing of URC data. Users can customize the addition of URC data and its execution functions to the management list, so the processing of URC data is also the main porting work of AT Client.
 
@@ -697,7 +697,7 @@ typedef struct at_urc *at_urc_t;
 Each URC data has a structure control block that defines and determines the prefix and suffix of the URC data, as well as the execution function of the URC data. A piece of data can be defined as URC data only if it matches the prefix and suffix of the URC exactly. The URC data execution function is executed immediately after the matching URC data is obtained. So developers adding a URC data requires a custom matching prefix, suffix, and execution function.
 
 
-#### URC Data List Initialization
+### URC Data List Initialization
 
 ```c
 void at_set_urc_table(const struct at_urc *table, rt_size_t size);
@@ -745,9 +745,9 @@ int at_client_port_init(void)
 }
 ```
 
-### AT Client Other APIs Introduction
+## AT Client Other APIs Introduction
 
-#### Send Specified Length Data
+### Send Specified Length Data
 
 ```c
 rt_size_t at_client_send(const char *buf, rt_size_t size);
@@ -763,7 +763,7 @@ rt_size_t at_client_send(const char *buf, rt_size_t size);
 
 This function is used to send the specified length data to the AT Server device through the AT Client device, which is mostly used for the AT Socket function.
 
-#### Receive Specified Length Data
+### Receive Specified Length Data
 
 ```c
 rt_size_t at_client_recv(char *buf, rt_size_t size,rt_int32_t timeout);
@@ -780,7 +780,7 @@ rt_size_t at_client_recv(char *buf, rt_size_t size,rt_int32_t timeout);
 
 This function is used to receive data of a specified length through the AT Client device, and is mostly used for the AT Socket function. This function can only be used in URC callback handlers.
 
-#### Set the line terminator for receiving data ####
+### Set the line terminator for receiving data
 
 ```c
 void at_set_end_sign(char ch);
@@ -794,7 +794,7 @@ void at_set_end_sign(char ch);
 
 This function is used to set the line terminator, which is used to judge the end of a row of data received by the client, and is mostly used for the AT Socket function.
 
-#### Waiting for module initialization to complete ####
+### Waiting for module initialization to complete
 
 ```c
 int at_client_wait_connect(rt_uint32_t timeout);
@@ -809,7 +809,7 @@ int at_client_wait_connect(rt_uint32_t timeout);
 
 This function is used to cyclically send AT commands when the AT module starts, until the module responds to the data, indicating that the module is successfully started.
 
-### AT Client Multi-Client Support ###
+## AT Client Multi-Client Support
 
 In general, the device as the AT Client only connects to one AT module (the AT module acts as the AT Server) and can directly use the above functions of data transmission and reception and command parsing. In a few cases, the device needs to connect multiple AT modules as the AT Client. In this case, the multi-client support function of the device is required.
 
@@ -882,16 +882,16 @@ at_delete_resp(resp);
 
 The process differences used by other functions are similar to the above `at_obj_exec_cmd()` function. The main function is to obtain the client object through the `at_client_get()` function, and then determine which client is the client through the incoming object to achieve multi-client support.
 
-## FAQs
+# FAQs
 
-### Q: What should I do if the log on the shell shows an error when enabling the AT command to send and receive data real-time printing function. ?
+## Q: What should I do if the log on the shell shows an error when enabling the AT command to send and receive data real-time printing function. ?
 
 **A:** Increase the baudrate of the serial port device corresponding to the shell to 921600, improve the serial port printing speed, and prevent the printing error when the data is too large.
 
-### Q: When the AT Socket function is started, the compile prompt "The AT socket device is not selected, please select it through the env menuconfig".
+## Q: When the AT Socket function is started, the compile prompt "The AT socket device is not selected, please select it through the env menuconfig".
 
 **A:** After the AT Socket function is enabled, the corresponding device model is enabled in the at device package by default. Enter the at device package, configure the device as an ESP8266 device, configure WIFI information, re-generate the project, compile and download.
 
-### Q: AT Socket function data reception timeout or data reception is not complete.
+## Q: AT Socket function data reception timeout or data reception is not complete.
 
 **A:** The error may be that the receive data buffer in the serial device used by the AT is too small (RT_SERIAL_RB_BUFSZ default is 64 bytes), and the data is overwritten after the data is not received in time. The buffer size of the serial port receiving data (such as 256 bytes) is appropriately increased.

documentation/basic/basic.md

@@ -1,4 +1,4 @@
-# Kernel Basics
+@page kernel_basics Kernel Basics
 
 This chapter gives a brief introduction to the software architecture of the RT-Thread kernel, beginning with its composition and implementation.  While also introducing RT-Thread kernel-related concepts for beginners.
 After understanding this chapter, readers will have an elementary understanding of the RT Thread kernel and will be able to answer questions such as -
@@ -10,15 +10,7 @@ After understanding this chapter, readers will have an elementary understanding
 
 In the nutshell, this is only a brief introduction to software architecture decomposition and implementation of the real-time kernel. This will give understanding and concepts of how RT-Thread kernel works togther. After learning from this chapter, readers will have basic knowledge of each kernel components, system booting up proccesses, memory allocation and distrubtion, and methods of kernel configuration.
 
-## **Table of Contents**
-
-1. [Introduction to RT-Thread Kernel](#introduction-to-rt-thread-kernel)
-2. [RT-Thread Startup Process](#rt-thread-startup-process)
-3. [RT-Thread Program Memory Distribution](#rt-thread-program-memory-distribution)
-4. [RT-Thread Automatic Initialization Mechanism](#rt-thread-automatic-initialization-mechanism)
-5. [RT-Thread Kernel Object Model](#rt-thread-kernel-object-model)
-
-## Introduction to RT-Thread Kernel
+# Introduction to RT-Thread Kernel
 
 Kernel is the most basic and fundenmental part of an Operating System. Kernel service library and RT-Thread kernel libraries are interfacing between hardware and components/service layer. This includes the implementation of real-time kernel service library (rtservice.h/kservice.c) and other RT-Thread kernel libraries such as object management, thread management and scheduler, inter-thread communication management, clock management and memory management respectively. Below diagram is the core architecture diagram of the core kernel.
 
@@ -30,7 +22,7 @@ Implementation of core kernel libraries are similar to a small set of standard C
 The built of the Kernel will be vary depending on the complier. For example, using GNU GCC compiler, it will use more implementation from the standard C library. Last but not least, the minimum resource requirements of the Kernel is 3KB ROM and 1.2KB RAM.
 
 
-### Thread Scheduling
+## Thread Scheduling
 
 Thread is the smallest scheduling unit in the RT-Thread operating system. The thread scheduling algorithm is a **Priority-based Full Preemptive Multi-Thread** scheduling algorithm.
 The system can support up to 256(0 - 255) thread priorities. For systems with tight resources, configurations with 8 or 32 thread priorities can be chosen(For example, STM32 has 32 thread priorities as per the default configuration). Lower numbers have a higher priority where 0 represents the highest priority furthermore the lowest priority(highest number) is reserved for idle threads.
@@ -39,7 +31,7 @@ The number of threads is bounded by the memory of the hardware platform and not
 
 Thread management will be covered in detail in the "Thread Management" chapter.
 
-### Clock Management
+## Clock Management
 
 RT-Thread's Clock management is based upon a **clock beat**, which is the smallest clock unit in the RT-Thread operating system.
 The RT-Thread timer provides two types of timer mechanisms:
@@ -52,7 +44,7 @@ The timer service is concluded using a timer timing callback i.e. a timeout func
 
 Timer will be explained further in the "Clock Management" chapter.
 
-### Synchronization between Threads
+## Synchronization between Threads
 
 RT-Thread uses thread semaphores, mutexes, and event sets to achieve inter-thread synchronization.
 Thread synchronizations happen through the acquisition and release of semaphore and mutexes.
@@ -61,13 +53,13 @@ Event sets are primarily used for synchronization between threads, they can achi
 
 The concepts of semaphores, mutexes, and event sets are detailed in the "Inter-Thread Synchronization" chapter.
 
-### Inter-Thread Communication
+## Inter-Thread Communication
 
 RT-Thread supports communication mechanisms such as mailbox, message queue, etc. The mailbox's message length is fixed to 4 bytes. Whereas, message queue can receive messages in variable size and cache the messages in its own memory space.  
 Compared to a message queue, a mailbox is more efficient. The sending action of the mailbox and message queue can be safely used in an ISR (Interrupt Service Routine). The communication mechanism allows threads to wait by priority or to acquire by the First In First Out (FIFO) method.  
 The concept of mailbox and message queue will be explained in detail in the "Inter-Thread Communication" chapter.
 
-### Memory Management
+## Memory Management
 
 RT-Thread allows:
 1. Static Memory Pool
@@ -82,13 +74,13 @@ There is also a dynamic memory heap management called memheap, suitable for memo
 
 The concept of memory management will be explained in the "Memory Management" chapter.
 
-### I/O Device Management
+## I/O Device Management
 
 RT-Thread uses I2C, SPI, USB, UART, etc., as peripheral devices and is uniformly registered through the device. It realized a device management subsystem accessed by the name, and it can access hardware devices according to a unified API interface. On the device driver interface, depending on the characteristics of the embedded system, corresponding events can be attached to different devices. The driver notifies the upper application program when the device event is triggered.
 
 The concept of I/O device management will be explained in the "Device Model" and "General Equipment" chapters.
 
-## RT-Thread Startup Process
+# RT-Thread Startup Process
 
 The understanding of most codes usually starts from learning the startup process. We will firstly look for the source of the startup. Taking MDK-ARM as an example, the user program entry for MDK-ARM is the main() function located in the main.c file. The launching of the system starts from the assembly code startup_stm32f103xe.s, jumps to the C code, initializes the RT-Thread system function, and finally enters the user program entry main().
 
@@ -172,7 +164,7 @@ int main(void)
 }
 ```
 
-## RT-Thread Program Memory Distribution
+# RT-Thread Program Memory Distribution
 
 The general MCU contains storage space that includes the on-chip Flash and the on-chip RAM. RAM is equivalent to memory, and Flash is comparable to a hard disk. The compiler classifies a program into several parts stored in different memory areas of the MCU.
 
@@ -239,7 +231,7 @@ void sensor_init()
 ```
 The `sensor_value` is stored in the ZI segment and is automatically initialized to zero after system startup (some library functions provided by the user program or compiler are initialized to zero). The sensor_inited variable is stored in the RW segment, and the sensor_enable is stored in the RO segment.
 
-## RT-Thread Automatic Initialization Mechanism
+# RT-Thread Automatic Initialization Mechanism
 
 The automatic initialization mechanism means that the initialization function does not need to be called by explicit function. It only needs to be declared by macro definition at the function definition, and it will be executed during system startup.
 
@@ -288,10 +280,9 @@ The macro interface definitions used to implement the automatic initialization f
 
 Initialization function actively declares through these macro interfaces, such as INIT_BOARD_EXPORT (rt_hw_usart_init), the linker will automatically collect all the declared initialization functions, placed in the RTI symbol segment, the symbol segment is located in the RO segment of the memory distribution. All functions in this RTI symbol segment are automatically called when the system is initialized.
 
-RT-Thread Kernel Object Model
----------------------
+# RT-Thread Kernel Object Model
 
-### Static and Dynamic Objects
+## Static and Dynamic Objects
 
 The RT-Thread kernel is designed with object-oriented method. The system-level infrastructures are all kernel objects such as threads, semaphores, mutexes, timers, and more. Kernel objects fall into two categories: static kernel objects and dynamic kernel objects. Static kernel objects are usually placed in RW and ZI segments, initialized in the program after system startup; dynamic kernel objects are created from the memory heap and then manually initialized.
 
@@ -372,7 +363,7 @@ In this example, thread1 is a static thread object and thread2 is a dynamic thre
 
 Static objects take up RAM space and is not depend on the memory heap manager. When allocating static objects, the time needed is determined. Dynamic objects depend on the memory heap manager. It requests RAM space while running. When the object is deleted, the occupied RAM space is released. These two methods have their own advantages and disadvantages, and can be selected according to actual needs.
 
-### Kernel Object Management Structure
+## Kernel Object Management Structure
 
 RT-Thread uses the kernel object management system to access/manage all kernel objects. Kernel objects contain most of the facilities in the kernel. These kernel objects can be statically allocated static objects and dynamic objects allocated from the system memory heap. .
 
@@ -396,7 +387,7 @@ The advantages of this design approach are:
 
 Derivations from object control block rt_object in the above figure includes: thread object, memory pool object, timer object, device object and IPC object (IPC: Inter-Process Communication. In RT-Thread real-time operating system, IPC objects is used for synchronization and communicate between threads); derivations from IPC objects includes: semaphores, mutexes, events, mailboxes, message queues, signals, etc.
 
-### Object Control Block
+## Object Control Block
 
 Data structure of kernel object control block:
 
@@ -452,7 +443,7 @@ enum rt_object_class_type
 
 From the above type specification, we can see that if it is a static object, the highest bit of the object type will be 1 (which is the OR operation of RT_Object_Class_Static and other object types and operations).  Otherwise it will be dynamic object, and the maximum number of object classes that the system can accommodate is 127.
 
-### Kernel Object Management
+## Kernel Object Management
 
 Data structure of kernel object container:
 
@@ -470,7 +461,7 @@ struct rt_object_information
 
 A class of objects is managed by an rt_object_information structure, and each practical instance of such type of object is mounted to the object_list in the form of a linked list. The memory block size of this type of object is identified by object_size (the memory block each practical instance of each type of object is the same size).
 
-#### Initialization Object
+### Initialization Object
 
 An uninitialized static object must be initialized before it can be used. The initialization object uses the following interfaces:
 
@@ -489,7 +480,7 @@ When this function is called to initialize the object, the system will place the
 | type     | The type of the object must be a enumeration type listed in rt_object_class_type, RT_Object_Class_Static excluded. (For static objects, or objects initialized with the rt_object_init interface, the system identifies it as an RT_Object_Class_Static type) |
 | name     | Name of the object. Each object can be set to a name, and the maximum length for the name is specified by RT_NAME_MAX. The system does not care if it uses ’`\0`’as a terminal symbol. |
 
-#### Detach Object
+### Detach Object
 
 Detach an object from the kernel object manager. The following interfaces are used to detach objects:
 
@@ -499,7 +490,7 @@ void rt_object_detach(rt_object_t object);
 
 Calling this interface makes a static kernel object to be detached from the kernel object container, meaning the corresponding object node is deleted from the kernel object container linked list. After the object is detached, the memory occupied by the object will not be released.
 
-#### Allocate object
+### Allocate object
 
 The above descriptions are interfaces of objects initialization and detachment, both of which are under circumstances that object-oriented memory blocks already exist. But dynamic objects can be requested when needed. The memory space is freed for other applications when not needed. To request assigning new objects, you can use the following interfaces:
 
@@ -519,7 +510,7 @@ When calling the above interface, the system first needs to obtain object inform
 | object handle allocated successfully | Allocate successfully |
 | RT_NULL            | Fail to allocate               |
 
-#### Delete Object
+### Delete Object
 
 For a dynamic object, when it is no longer used, you can call the following interface to delete the object and release the corresponding system resources:
 
@@ -534,7 +525,7 @@ When the above interface is called, the object is first detached from the object
 |----------|------------|
 | object   | object handle |
 
-#### Identify objects
+### Identify objects
 
 Identify whether the specified object is a system object (static kernel object). The following interface is used to identify the object:
 

documentation/contribution_guide/coding_style_en.md

@@ -1,4 +1,4 @@
-                           RT-Thread Coding Style
+@page rtt_code_style_en RT-Thread Coding Style
 
 This is an developing instruction for RT-Thread developers. As open source
 software, RT-Thread is created by the cooperation of different people. This
@@ -7,7 +7,7 @@ RT-Thread users should also get to know some conventions in the code through it
 and thus easier to understand the implementations of RT-Thread.
 
 
-1. Directory Naming
+# 1. Directory Naming
 
 In normal conditions, please name directories in lowercase. Directories should
 have descriptive names. For example, the port of a chip should be composed of
@@ -15,14 +15,14 @@ the name of the chip and the category of the chip. Directories under components/
 should name what the component does.
 
 
-2. File Naming
+# 2. File Naming
 
 In normal conditions, please name files in lowercase. If the file is
 referencing other places, it can have the original name. To avoid naming
 collision, do not use general names or the names that are frequently used.
 
 
-3. Header Files
+# 3. Header Files
 
 To avoid include the same header file for multiple times, you need to define a
 symbol like this:
@@ -36,7 +36,7 @@ The symbol should begin and end with "__" to avoid naming collision. The words
 of the file name should be connected by "_". (This convention is called "snake case".)
 
 
-4. Header File Comments
+# 4. Header File Comments
 
 In every header file, there should be copyright information and Change Log
 record like this:
@@ -52,7 +52,7 @@ record like this:
     * 2006-04-26     Bernard      add semaphore APIs
     */
 
-5. Structure Defines
+# 5. Structure Defines
 
 Please name structures in lowercase and connect words with "_". For example:
 
@@ -76,7 +76,7 @@ example:
     typedef struct rt_timer* rt_timer_t;
 
 
-6. Macros
+# 6. Macros
 
 In RT-Thread, please use uppercase names for macro definitions. Words are
 connected by "_". Like:
@@ -84,7 +84,7 @@ connected by "_". Like:
     #define RT_TRUE                         1
 
 
-7. Function Naming and Declaration
+# 7. Function Naming and Declaration
 
 Please name functions in lowercase. Separate words with "_". The API provided to
 upper application should be declared in header files. If the function don't have
@@ -93,7 +93,7 @@ parameters, it should be declared as void:
     rt_thread_t rt_thread_self(void);
 
 
-8. Commenting
+# 8. Commenting
 
 Please use English to comment. There shouldn't be many comments as the
 comments should describe what the code does. It should describe complicated
@@ -101,7 +101,7 @@ algorithms, for example. Comments for statements should be placed before the
 statements or to the right of them. Any other locations are invalid.
 
 
-9. Indent
+# 9. Indent
 
 Please use TAB or 4 spaces to indent. It's preferred to use 4 spaces. If no
 other special meanings, the indent should begin right after "{":
@@ -123,7 +123,7 @@ aligned with "switch":
 "case" is aligned with "switch". The following code block should be indented.
 
 
-10. Braces and Spaces
+# 10. Braces and Spaces
 
 For ease of reading, it is advised that braces should occupy the whole line
 instead of following other statements. Like:
@@ -160,7 +160,7 @@ operators and the strings. There should be no spaces around(inside) parentheses,
 This is a bad practice.
 
 
-11. trace, log Information
+# 11. trace, log Information
 
 In RT-Thread, rt_kprintf is a commonly used logging routine. In RT-Thread
 rt_kprintf is implemented as a polling, non-interrupting string output. It is
@@ -175,14 +175,14 @@ variable or a macro). When logging, it should be easy to understand and easy to
 determine where the problem is.
 
 
-12. Functions
+# 12. Functions
 
 Functions in kernel should be K.I.S.S. ("Keep it simple, stupid.") If the function
 is too long, you should split it into smaller ones, with each of them simplified to
 be easy to understand.
 
 
-13. Objects
+# 13. Objects
 
 The kernel of RT-Thread uses object-oriented techniques in C. The naming convention
 is: structure names are the object names, object names + verb phrases are the
@@ -211,7 +211,7 @@ When creating a new object, think twice on memory allocations: whether a static
 object could be created or it could only created dynamically on the heap. Allocations
 can be slower, but may be necessary in dynamic environments.
 
-14. Use astyle to format the code automatically
+# 14. Use astyle to format the code automatically
 parameters: --style=allman
             --indent=spaces=4
             --indent-preproc-block

documentation/device/adc/adc.md

@@ -1,10 +1,10 @@
-# ADC Device
+@page device_adc ADC Device
 
-## An Introduction to ADC
+# An Introduction to ADC
 
 An ADC (analog-to-digital converter) is a hardware device that converts continuously changing analog signals to discrete digital signals. Usually, these analog signals include temperature, pressure, sound, video and many other types of signals. Converting them is important, as digital signals are easier to store, process, and transmit. This conversion can be achieved by using an ADC device which is commonly integrated in various platforms. Historically, ADCs were first used to convert received wireless signals to digital signals, for example, television signals, or signals from long-short broadcast stations.
 
-### Conversion Process
+## Conversion Process
 
 As shown in the figure below, the analog-to-digital conversion generally involves steps of sampling, holding, quantifying, and encoding. In actual circuits, some processes are combined, such as sampling and holding, while quantization and encoding are implemented simultaneously in the conversion process.
 
@@ -14,19 +14,19 @@ Sampling is the conversion of analog signals that changes continuously over time
 
 The process of converting a numerically continuous analog quantity into a digital quantity is called quantization. Digital signals are discrete numerically. The output voltage of the sample-and-hold circuit also needs to be naturalized to a corresponding discrete level in a similar way, and any digital quantity can only be an integer multiple of a certain minimum quantity unit. The quantized value also requires the encoding process, which is the digital output of the A/D converter.
 
-### Resolution
+## Resolution
 
 Resolution is represented as binary (or decimal) numbers. Generally, it comes in 8 bits, 10 bits, 12 bits, 16 bits, etc. A larger resolution, in bits,  means more accuracy in the conversion of analog to digital signals.
 
-### Precision
+## Precision
 
 Precision is the maximum error value between analog signals and real ADC device numerical points’ values.An ADC with a high resolution might have a low precision, meaning that factors like noise can affect the numerical ADC reading more than small changes in the input signal.
 
-### Conversion Rate
+## Conversion Rate
 
 The conversion rate is the reciprocal of time taken for an ADC device to complete conversion from an analog to a digital signal. For example, an ADC device with a conversion rate of 1MHz means that the ADC conversion time is 1 microsecond.
 
-## Access ADC Device
+# Access ADC Device
 
 The application accesses the ADC hardware through the ADC device management interface provided by RT-Thread. The relevant interfaces are as follows:
 
@@ -37,7 +37,7 @@ The application accesses the ADC hardware through the ADC device management inte
 | rt_adc_read()   | Read ADC device data |
 | rt_adc_disable()  | Close the ADC device |
 
-### Find ADC Devices
+## Find ADC Devices
 
 The application gets the device handler based on the ADC device name to operate the ADC device. Following is the interface function to find the devices: 
 
@@ -62,7 +62,7 @@ rt_adc_device_t adc_dev;            /* ADC device handle */
 adc_dev = (rt_adc_device_t)rt_device_find(ADC_DEV_NAME);
 ```
 
-### Enable ADC Channel
+## Enable ADC Channel
 
 It is required to enable the ADC device with the following interface function before reading and operating the ADC device.
 
@@ -91,7 +91,7 @@ adc_dev = (rt_adc_device_t)rt_device_find(ADC_DEV_NAME);
 rt_adc_enable(adc_dev, ADC_DEV_CHANNEL);
 ```
 
-### Read ADC Channel Sample Values
+## Read ADC Channel Sample Values
 
 Reading the ADC channel sample values can be done by the following function:
 
@@ -129,7 +129,7 @@ rt_kprintf("the voltage is :%d.%02d \n", vol / 100, vol % 100);
 
 The calculation formula of the actual voltage value is: `sampling value * reference voltage/(1 << resolution digit)`.  In the above example,  variable *vol* was enlarged 100 times, so finally the integer part of voltage is obtained through *vol / 100*, and the decimal part of voltage is obtained through *vol % 100*.
 
-### Disabling the ADC Channel
+## Disabling the ADC Channel
 
 An ADC channel can be disabled through the following function:
 
@@ -166,7 +166,7 @@ rt_kprintf("the voltage is :%d.%02d \n", vol / 100, vol % 100);
 rt_adc_disable(adc_dev, ADC_DEV_CHANNEL);
 ```
 
-### FinSH Command
+## FinSH Command
 
 To find out the registered device, you can use the command adc probe followed by the registered ADC device name as following,
 
@@ -198,7 +198,7 @@ adc1 channel 5 disable success
 msh >
 ```
 
-## ADC Device Usage Example
+# ADC Device Usage Example
 
 The specific usage of the ADC device can refer to the following sample code. The main steps of the sample code are as follows: