doxygen: add prefix for page name (#9989)

unicornx · web-flow · commit f6f7d91a61c9 · 2025-02-13T23:28:19.000+08:00
Add prefix "page_" to the name of pages.

Add this as a rule in guide of writing doxygen documents.

Signed-off-by: Chen Wang &lt;unicorn_wang@outlook.com&gt;
diff --git a/documentation/0.doxygen/INDEX.md b/documentation/0.doxygen/INDEX.md
@@ -1,8 +1,8 @@
-@page howto_doxygen How to write doxygen documentation for RT-Thread
+@page page_howto_doxygen How to write doxygen documentation for RT-Thread
 
 RT-Thread Online Documentation is created based on doxygen and is available at: <https://rt-thread.github.io/rt-thread/>. It is consisted of two parts.
 
-One part is the detailed introduction of Kernel, which is written in markdown format and converted into HTML page by doxygen. It is displayed under "RT-Thread User Guide" in Treeview on the left side of the browser. Each sub-chapter is organized into a hierarchical structure by using doxygen's [subpage mechanism][2]. There are no special requirements for writing this part, so I will not go into details in this article.
+One part is the detailed introduction of Kernel, which is written in markdown format and converted into HTML page by doxygen. It is displayed under "RT-Thread User Guide" in Treeview on the left side of the browser. Each sub-chapter is organized into a hierarchical structure by using doxygen's [subpage mechanism][2]. To define a page, we use `@page` command. The page name should be prefixed with a "page_", and the page name should be unique. Besides this, there are no special requirements for writing this part, so I will not go into details in this article.
 
 The other part is the description of API. RT-Thread uses [doxygen][1] to automate the generation of documentation from source code comments, parsing information about classes, functions, and variables to produce output in format of HTML. It is displayed under "Modules" in Treeview on the left side of the browser. Each sub-chapter is organized into a hierarchical structure by using doxygen's [topics mechanism][3]. The main content of this article is to describe how to write API with doxygen.
 
diff --git a/documentation/1.introduction/introduction.md b/documentation/1.introduction/introduction.md
@@ -1,4 +1,4 @@
-@page introduction Introduction
+@page 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.  
 
diff --git a/documentation/2.quick-start/keil-installation/keil-installation.md b/documentation/2.quick-start/keil-installation/keil-installation.md
@@ -1,4 +1,4 @@
-@page quickstart_keil Keil MDK Installation
+@page 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.
 
diff --git a/documentation/2.quick-start/quick-start.md b/documentation/2.quick-start/quick-start.md
@@ -1,4 +1,4 @@
-@page quick_start Start Guide
+@page 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.
 
@@ -10,7 +10,7 @@ What will follow is a demonstration of RT-Thread running on a simulated STM32F10
 
 # 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: @subpage quickstart_keil.
+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 page_quickstart_keil.
 
 # First acquaintance with RT-Thread
 
diff --git a/documentation/3.kernel/INDEX.md b/documentation/3.kernel/INDEX.md
@@ -1,10 +1,10 @@
-@page kernel Kenrel
+@page 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
+- @subpage page_kernel_basics
+- @subpage page_thread_management
+- @subpage page_clock_management
+- @subpage page_thread_sync
+- @subpage page_thread_comm
+- @subpage page_memory_management
+- @subpage page_interrupt_management
+- @subpage page_kernel_porting
diff --git a/documentation/4.tool/INDEX.md b/documentation/4.tool/INDEX.md
@@ -1,5 +1,5 @@
-@page tool Tool
+@page page_tool Tool
 
-- @subpage env
+- @subpage page_env
 
-- @subpage scons
+- @subpage page_scons
diff --git a/documentation/5.device/INDEX.md b/documentation/5.device/INDEX.md
@@ -1,14 +1,14 @@
-@page device Device
+@page 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
+- @subpage page_device_framework
+- @subpage page_device_pin
+- @subpage page_device_uart
+- @subpage page_device_adc
+- @subpage page_device_i2c
+- @subpage page_device_spi
+- @subpage page_device_pwm
+- @subpage page_device_rtc
+- @subpage page_device_hwtimer
+- @subpage page_device_watchdog
+- @subpage page_device_wlan
+- @subpage page_device_sensor
diff --git a/documentation/6.components/INDEX.md b/documentation/6.components/INDEX.md
@@ -1,12 +1,12 @@
-@page components Components
+@page 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
+- @subpage page_component_finsh
+- @subpage page_component_vfs
+- @subpage page_component_utest
+- @subpage page_component_dlmodule
+- @subpage page_component_sal
+- @subpage page_component_at
+- @subpage page_component_posix
+- @subpage page_component_ulog
+- @subpage page_component_pm
+- @subpage page_component_network
diff --git a/documentation/7.contribution/INDEX.md b/documentation/7.contribution/INDEX.md
@@ -1,11 +1,11 @@
-@page code_contribution Contribution
+@page 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
+@subpage page_rtt_code_style_en
 
-@subpage howto_doxygen
+@subpage page_howto_doxygen
diff --git a/documentation/INDEX.md b/documentation/INDEX.md
@@ -1,52 +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
+@subpage page_introduction
+
+@subpage page_quick_start
+
+@subpage page_kernel
+
+- @ref page_kernel_basics
+- @ref page_thread_management
+- @ref page_clock_management
+- @ref page_thread_sync
+- @ref page_thread_comm
+- @ref page_memory_management
+- @ref page_interrupt_management
+- @ref page_kernel_porting
+
+@subpage page_tool
+
+- @ref page_env
+- @ref page_scons
+
+@subpage page_device
+
+- @ref page_device_framework
+- @ref page_device_pin
+- @ref page_device_uart
+- @ref page_device_adc
+- @ref page_device_i2c
+- @ref page_device_spi
+- @ref page_device_pwm
+- @ref page_device_rtc
+- @ref page_device_hwtimer
+- @ref page_device_watchdog
+- @ref page_device_wlan
+- @ref page_device_sensor
+
+@subpage page_components
+
+- @ref page_component_finsh
+- @ref page_component_vfs
+- @ref page_component_utest
+- @ref page_component_dlmodule
+- @ref page_component_sal
+- @ref page_component_at
+- @ref page_component_posix
+- @ref page_component_ulog
+- @ref page_component_pm
+- @ref page_component_network
+
+@subpage page_code_contribution
 
diff --git a/documentation/at/at.md b/documentation/at/at.md
@@ -1,4 +1,4 @@
-@page component_at AT Commands
+@page page_component_at AT Commands
 
 # Introduction to AT Commands
 
diff --git a/documentation/basic/basic.md b/documentation/basic/basic.md
@@ -1,4 +1,4 @@
-@page kernel_basics Kernel Basics
+@page 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 -
diff --git a/documentation/contribution_guide/coding_style_en.md b/documentation/contribution_guide/coding_style_en.md
@@ -1,4 +1,4 @@
-@page rtt_code_style_en RT-Thread Coding Style
+@page 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
diff --git a/documentation/device/adc/adc.md b/documentation/device/adc/adc.md
@@ -1,4 +1,4 @@
-@page device_adc ADC Device
+@page page_device_adc ADC Device
 
 # An Introduction to ADC
 
diff --git a/documentation/device/device.md b/documentation/device/device.md
@@ -1,4 +1,4 @@
-@page device_framework I/O Device Framework
+@page page_device_framework I/O Device Framework
 
 Most embedded systems include some I/O (Input/Output) devices, data displays on instruments, serial communication on industrial devices, Flash or SD cards for saving data on data acquisition devices,as well as Ethernet interfaces for network devices, are examples of I/O devices that are commonly seen in embedded systems.
 
diff --git a/documentation/device/hwtimer/hwtimer.md b/documentation/device/hwtimer/hwtimer.md
@@ -1,4 +1,4 @@
-@page device_hwtimer HWTIMER Device
+@page page_device_hwtimer HWTIMER Device
 
 # Introduction to the Timer
 
diff --git a/documentation/device/i2c/i2c.md b/documentation/device/i2c/i2c.md
@@ -1,4 +1,4 @@
-@page device_i2c I2C Bus Device
+@page page_device_i2c I2C Bus Device
 
 # Introduction of I2C
 
diff --git a/documentation/device/pin/pin.md b/documentation/device/pin/pin.md
@@ -1,4 +1,4 @@
-@page device_pin PIN Device
+@page page_device_pin PIN Device
 
 # Introduction of Pin
 
diff --git a/documentation/device/pwm/pwm.md b/documentation/device/pwm/pwm.md
@@ -1,4 +1,4 @@
-@page device_pwm PWM Device
+@page page_device_pwm PWM Device
 
 # Introduction to PWM
 
diff --git a/documentation/device/rtc/rtc.md b/documentation/device/rtc/rtc.md
@@ -1,4 +1,4 @@
-@page device_rtc RTC Device
+@page page_device_rtc RTC Device
 
 # Introduction of RTC
 
diff --git a/documentation/device/sensor/sensor.md b/documentation/device/sensor/sensor.md
@@ -1,4 +1,4 @@
-@page device_sensor Sensor Device
+@page page_device_sensor Sensor Device
 
 # Introduction
 
diff --git a/documentation/device/spi/spi.md b/documentation/device/spi/spi.md
@@ -1,4 +1,4 @@
-@page device_spi SPI Device
+@page page_device_spi SPI Device
 
 # Introduction to SPI
 
diff --git a/documentation/device/uart/uart.md b/documentation/device/uart/uart.md
@@ -1,4 +1,4 @@
-@page device_uart UART Device
+@page page_device_uart UART Device
 
 # UART Introduction
 
diff --git a/documentation/device/watchdog/watchdog.md b/documentation/device/watchdog/watchdog.md
@@ -1,4 +1,4 @@
-@page device_watchdog WATCHDOG Device
+@page page_device_watchdog WATCHDOG Device
 
 # An Introduction to WATCHDOG
 
diff --git a/documentation/device/wlan/wlan.md b/documentation/device/wlan/wlan.md
@@ -1,4 +1,4 @@
-@page device_wlan WLAN Device
+@page page_device_wlan WLAN Device
 
 With the rapid development of the Internet of Things, more and more embedded devices are equipped with WIFI wireless network devices. In order to be able to manage WIFI network devices, RT-Thread introduces a WLAN device management framework. This framework has many features to control and manage WIFI, providing developers with many conveniences for using WIFI devices.
 
diff --git a/documentation/dlmodule/README.md b/documentation/dlmodule/README.md
@@ -1,4 +1,4 @@
-@page component_dlmodule Dynamic Module: dlmodule
+@page page_component_dlmodule Dynamic Module: dlmodule
 
 In traditional desktop operating systems, user space and kernel space are separate. The application runs in user space, and the kernel and kernel modules run in kernel space. The kernel module can be dynamically loaded and deleted to extend the kernel functionality.  `dlmodule` is a software component of the dynamic module loading mechanism provided in kernel space of RT-Thread. In versions of RT-Thread v3.1.0, this was also called the `Application Module`. After RT-Thread v3.1.0 and later, it returned to the tradition and was named after the `dynamic module`.
 
@@ -295,7 +295,7 @@ This function closes the dynamic library pointed to by  `handle` and unloads it
 
 # FAQs
 
-Please refer to @ref env for issues related to the Env tool.
+Please refer to @ref page_env for issues related to the Env tool.
 
 ## Q: Dynamic modules cannot be run successfully according to the documentation.
 
diff --git a/documentation/env/env.md b/documentation/env/env.md
@@ -1,4 +1,4 @@
-@page env User Manual of Env
+@page page_env User Manual of Env
 
 Env is a handy utility tool developed by RT-Thread team to build environment, graphical system configuration, and packages management for software projects that intend to run on RT-Thread operating system. Env tool come with source code builder, compilation environment and package management system.
 
@@ -82,7 +82,7 @@ scons --target=mdk4
 scons --target=mdk5
 ```
 
-For more scons tutorials, please refer to  @ref scons.
+For more scons tutorials, please refer to  @ref page_scons.
 
 ## BSP configuration: menuconfig
 
diff --git a/documentation/filesystem/README.md b/documentation/filesystem/README.md
@@ -1,4 +1,4 @@
-@page component_vfs Virtual File System
+@page page_component_vfs Virtual File System
 
 In early days, the amount of data to be stored in embedded systems was relatively small and data types were relatively simple.
 The data were stored by directly writing to a specific address in storage devices. However, with today modern technology, embedded device's functions are getting complicated and required more data storage. Therefore, we need new data management methods to simplify and organize the data storage.
diff --git a/documentation/finsh/finsh.md b/documentation/finsh/finsh.md
@@ -1,4 +1,4 @@
-@page component_finsh FinSH Console
+@page page_component_finsh FinSH Console
 
 In the early days of computer development, before the advent of graphics systems, there was no mouse or even a keyboard. How did people interact with computers at the time? The earliest computers used a punched note to enter commands into the computer and write the program. Later, with the continuous development of computers, monitors and keyboards became the standard configuration of computers, but the operating system at this time did not support the graphical interface. Computer pioneers developed a software that accepts commands entered by the user, and after interpretation, passes it to The operating system and return the results of the operating system execution to the user. This program wraps around the operating system like a layer of shell, so it's called a shell.
 
diff --git a/documentation/interrupt/interrupt.md b/documentation/interrupt/interrupt.md
@@ -1,4 +1,4 @@
-@page interrupt_management Interrupt Management
+@page page_interrupt_management Interrupt Management
 
 Interrupts often occur in embedded operating systems. When the CPU is processing a normal task, an external urgent event has occurred, requiring the CPU to suspend the current task to handle the asynchronous event. After the external event has been handled, CPU then returns to the interrupted address to continue working on the previous task. The system that implements this function is called the interrupt system, and the source of the request requesting for the CPU interrupt is called the interrupt source. An interrupt is an exception. An exception is any event that causes the processor to move away from normal operation and execute special code. If it is not processed in time, the system will either encounter an error or face a complete breakdown. So appropriately handling exceptions to avoid errors is a very important part of improving software robustness (stability). The following picture is a simple interrupt diagram.
 
diff --git a/documentation/kernel-porting/kernel-porting.md b/documentation/kernel-porting/kernel-porting.md
@@ -1,8 +1,8 @@
-@page kernel_porting Kernel Porting
+@page page_kernel_porting Kernel Porting
 
 After learning the previous chapters, everyone has a better understanding of RT-Thread, but many people are not familiar with how to port the RT-Thread kernel to different hardware platforms. Kernel porting refers to the RT-Thread kernel running on different chip architectures and different boards. It can have functions such as thread management and scheduling, memory management, inter-thread synchronization and communication, and timer management. Porting can be divided into two parts: CPU architecture porting and BSP (Board support package) porting .
 
-This chapter will introduce CPU architecture porting and BSP porting. The CPU architecture porting part will be introduced in conjunction with the Cortex-M CPU architecture. Therefore, it is necessary to review "Cortex-M CPU Architecture Foundation" in the previous chapter @ref interrupt_management.  After reading this chapter, how to complete the RT-Thread kernel porting will be learned.
+This chapter will introduce CPU architecture porting and BSP porting. The CPU architecture porting part will be introduced in conjunction with the Cortex-M CPU architecture. Therefore, it is necessary to review "Cortex-M CPU Architecture Foundation" in the previous chapter @ref page_interrupt_management.  After reading this chapter, how to complete the RT-Thread kernel porting will be learned.
 
 # CPU Architecture Porting
 
diff --git a/documentation/memory/memory.md b/documentation/memory/memory.md
@@ -1,4 +1,4 @@
-@page memory_management Memory Management
+@page page_memory_management Memory Management
 
 In a computing system, there are usually two types of memory space: internal memory space and external memory space. Internal memory can be quickly accessed, its contents can be read to and changed and only an address is required. The contents of internal memory are deleted after each power off. It is what would usually be called RAM (Random Access Memory) and is analogous to the RAM in a desktop computer. On the other hand, external memory has relatively fixed contents, retains data even after power off. It is usually called ROM (Read-Only Memory) and is analogous to the hard disk in a desktop computer.
 
diff --git a/documentation/network/network.md b/documentation/network/network.md
diff --git a/documentation/pm/pm.md b/documentation/pm/pm.md
diff --git a/documentation/posix/README.md b/documentation/posix/README.md
diff --git a/documentation/sal/sal.md b/documentation/sal/sal.md
diff --git a/documentation/scons/scons.md b/documentation/scons/scons.md
diff --git a/documentation/thread-comm/thread-comm.md b/documentation/thread-comm/thread-comm.md
diff --git a/documentation/thread-sync/thread-sync.md b/documentation/thread-sync/thread-sync.md
diff --git a/documentation/thread/thread.md b/documentation/thread/thread.md
diff --git a/documentation/timer/timer.md b/documentation/timer/timer.md
diff --git a/documentation/ulog/ulog.md b/documentation/ulog/ulog.md
diff --git a/documentation/utest/utest.md b/documentation/utest/utest.md

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-@page introduction Introduction`
	`1`	`+@page page_introduction Introduction`
`2`	`2`
`3`	`3`	`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.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-@page quickstart_keil Keil MDK Installation`
	`1`	`+@page page_quickstart_keil Keil MDK Installation`
`2`	`2`
`3`	`3`	`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.`
`4`	`4`