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 <[email protected]>
Co-authored-by: Supper Thomas <[email protected]>

1 files changed, 18 insertions, 23 deletions

diff --git a/documentation/timer/timer.md b/documentation/timer/timer.md
index 921719dd7e..3004c7a3ad 100644
--- a/documentation/timer/timer.md
+++ b/documentation/timer/timer.md
@@ -1,16 +1,14 @@
-Clock Management
-========
+@page clock_management Clock & Timer Management
 
 The concept of time is very important. You need to set a time to go out with friends and it takes time to complete tasks. Life is inseparable from time. The same is true for operating systems, which require time to regulate the execution of their tasks. The smallest time unit in operating system is clock tick (OS Tick). This chapter focuses on introduction of clock ticks and clock-based timers. After reading this chapter, we will learn how clock ticks are generated and how to use RT-Thread timers.
 
-Clock Tick(OS Tick)
---------
+# Clock Tick(OS Tick)
 
 Any operating system needs to provide a clock tick for the system to handle all time-related events, such as thread latency, thread time slice rotation scheduling, timer timeout, etc. Clock tick is a specific periodic interrupt. This interrupt can be regarded as the system heartbeat. The time interval between interrupts depends on different applications, generally it is 1ms–100ms. The faster the clock tick rate, the greater the overhead of the system. The number of clock ticks counted from the start of the system is called the system time.
 
 In RT-Thread, the length of clock tick can be adjusted according to the value of RT_TICK_PER_SECOND, which is equal to 1/RT_TICK_PER_SECOND second.
 
-### Clock Tick Implementation
+## Clock Tick Implementation
 
 Clock tick is generated by a hardware timer configured in interrupt trigger mode.  `void rt_tick_increase(void)` will be called when an interrupt occurs,notifying the operating system that a system clock has passed; different hardware driver have different timer interrupt implementations. Here is an example of using STM32 `SysTick_Handler` to achieve clock Tick.
 
@@ -58,7 +56,7 @@ You can see that global variable rt_tick is incremented by one on every clock ti
 
 >In interrupt, rt_timer_check()  is used to check the system hardware timer linked list. If there is a timer timeout, the corresponding timeout function will be called. All timers are removed from the timer linked list if it timed out, and periodic timer is added to the timer linked list when it is started again.
 
-### Obtain Clock Tick
+## Obtain Clock Tick
 
 Since global variable rt_tick is incremented by one on every clock tick, the value of the current rt_tick will be returned by calling `rt_tick_get`, which is the current clock tick value. This interface can be used to record the length of time a system is running, or to measure the time it takes for a task to run. The interface function is as follows:
 
@@ -72,8 +70,7 @@ The following table describes the return values of `rt_tick_get()` function:
 |----------|----------------|
 | rt_tick  | Current clock tick value |
 
-Timer Management
-----------
+# Timer Management
 
 Timer refers to triggering an event after a certain specified time from a specified moment, for example, setting a timer to wake up yourself the next morning. Timer includes hardware timer and software timer:
 
@@ -83,7 +80,7 @@ Timer refers to triggering an event after a certain specified time from a specif
 
 RT-Thread operating system provides software-implemented timers in units of clock tick (OS Tick), that is, the timing value must be an integer multiple of OS Tick. For example, an OS Tick is 10ms, then the software timer can only be timed 10ms, 20ms, 100ms, etc., but not 15ms. RT-Thread timer is also based on the clock tick, providing timing capabilities based on integral multiples of the clock tick.
 
-### RT-Thread Timer Introduction
+## RT-Thread Timer Introduction
 
 RT-Thread timer provides two types of timer mechanisms: the first type is a one-shot timer, which only triggers a timer event for onetime after startup, and then the timer stops automatically. The second type is a periodic trigger timer, which periodically triggers a timer event until the user manually stops it, otherwise it will continue to execute forever.
 
@@ -91,7 +88,7 @@ In addition, according to the context in which the timeout function is executed,
 
 ![Timer Context](figures/05timer_env.png)
 
-#### HARD_TIMER Mode
+### HARD_TIMER Mode
 
 The timer timeout function of HARD_TIMER mode is executed in the interrupt context and can be specified with the parameter RT_TIMER_FLAG_HARD_TIMER when initializing/creating the timer.
 
@@ -99,11 +96,11 @@ When executed in interrupt context, the requirements for timeout function are th
 
 The default mode of RT-Thread timer is HARD_TIMER mode which means after the timer timeout, the timeout function runs in the context of the system clock interrupt. The execution mode in the interrupt context determines that the timer's timeout function should not call any system function that will cause the current context to suspend; nor can it be executing for a very long time, otherwise the response time of other interrupts will be lengthened or the running time of other threads will be preempted.
 
-#### SOFT_TIMER Mode
+### SOFT_TIMER Mode
 
 The SOFT_TIMER mode is configurable and macro definition RT_USING_TIMER_SOFT is used to determine whether the mode should be enabled. When this mode is enabled, the system will create a timer thread at initialization, and then the timer timeout function of SOFT_TIMER mode will be executed in the context of the timer thread. SOFT_TIMER mode can be specified using the parameter RT_TIMER_FLAG_SOFT_TIMER when initializing/creating the timer.
 
-### Timer Working Mechanism
+## Timer Working Mechanism
 
 The following is an example to illustrate the working mechanism of RT-Thread timer. Two important global variables are maintained in the RT-Thread timer module:
 
@@ -121,7 +118,7 @@ If after system's 10 ticks (current rt_tick=30),  a new task has created Timer4
 
 ![Timer linked List Insertion Diagram](figures/05timer_linked_list2.png)
 
-#### Timer Control Block
+### Timer Control Block
 
 In RT-Thread operating system, timer control block is defined by structure `struct rt_timer` and forms a timer kernel object, which is then linked to the kernel object container for management. It is a data structure used by the operating system to manage timers. It stores information about timers, such as the initial number of ticks, the number of timeout ticks, the linked list structure used to connect timers, timeout callback functions, etc.
 
@@ -141,7 +138,7 @@ typedef struct rt_timer *rt_timer_t;
 
 Timer control block is defined by  structure `struct rt_timer` and forms a timer kernel object, which is then linked to the kernel object container for management. The `list` member is used to link an active (already started) timer to the `rt_timer_list` linked list.
 
-#### Timer Skip List Algorithm
+### Timer Skip List Algorithm
 
 In the introduction of working mechanics of the timer above, we have talked about that the newly created and activated timers are inserted into the rt_timer_list linked list in the order of the timeout, that is, rt_timer_list linked list is an ordered list. RT-Thread uses a skip list algorithm to speed up the search for linked list elements.
 
@@ -161,7 +158,7 @@ In this structure, {3, 18, 77} is extracted as first-level index, so that the nu
 
 Therefore, the timer skip list can pass the index of the upper layer, reducing the number of comparisons during the search and improving the efficiency of the search. This is an algorithm of "space in exchange of time", macro definition RT_TIMER_SKIP_LIST_LEVEL is used to configure the number of layers in skip list. The default value is 1, which means that ordered linked list algorithm for first-order ordered list graph is used. Each additional one means that another level of index is added to the original list.
 
-### Timer Management
+## Timer Management
 
 RT-Thread timer is introduced in the previous sections and the working mechanism of the timer is conceptually explained. This section will go deep into the various interfaces of the timer to help the reader understand the RT-Thread timer at the code level.
 
@@ -181,7 +178,7 @@ Timer control block contains important parameters related to the timer and acts
 
 ![Timer Related Operations](figures/05timer_ops.png)
 
-#### Create and Delete Timer
+### Create and Delete Timer
 
 When dynamically creating a timer, the following function interface can be used:
 
@@ -236,7 +233,7 @@ Input parameters and return values of rt_timer_delete()
 |**Return**| ——                                                                      |
 | RT_EOK   | Deletion is successful (if the parameter timer handle is RT_NULL, it will result in an ASSERT assertion) |
 
-#### Initialize and Detach Timer
+### Initialize and Detach Timer
 
 When creating a timer statically , the timer can be initialized by using `rt_timer_init` interface. The function interface is as follows:
 
@@ -277,7 +274,7 @@ Input parameters and return values for `rt_timer_detach()`
 |**Return **| ——                                   |
 | RT_EOK   | Successfully detached     |
 
-#### Start and Stop Timer
+### Start and Stop Timer
 
 When the timer is created or initialized, it will not be started immediately. It will start after timer function interface is called. The timer function interface is started as follows:
 
@@ -314,7 +311,7 @@ After the timer stop function interface is called, the timer state will change t
 | RT_EOK      | Timer successfully stopped |
 | \- RT_ERROR | timer is in stopped state |
 
-#### Control Timer
+### Control Timer
 
 In addition to some of the programming interfaces provided above, RT-Thread additionally provides a timer control function interface to obtain or set more timer information. The control timer function interface is as follows:
 
@@ -345,8 +342,7 @@ Commands supported by function parameters cmd:
 
 See "dynamic timer routine" for code that uses the timer control interface.
 
-Timer Application Sample
---------------
+# Timer Application Sample
 
 This is an example of creating a timer that creates two dynamic timers, one for one shot timing, another one for periodic timing and for the periodic timer to run for a while and then stop running, as shown below:
 
@@ -498,8 +494,7 @@ periodic timer is timeout
 
 The timeout function of periodic timer1 runs once every 10 OS Ticks for 10 times (After 10 times rt_timer_stop is called to stop timer1); the timeout function of one-shot timer2 runs once on the 30th OS Tick.
 
-High Precision Delay
-----------
+# High Precision Delay
 
 The minimum precision of the RT-Thread timer is determined by the system clock tick (1 OS Tick = 1/RT_TICK_PER_SECOND second, RT_TICK_PER_SECOND value is defined in the rtconfig.h file), and the timer must be set to an integer multiple of the OS Tick. When it is necessary to implement system timing for a shorter time length. For example, the OS Tick is 10ms but the program needs to implement a timing or delay of 1ms. In this case, the operating system timer can't meet the requirements. This problem can be solved by reading the counter of a hardware timer of the system or using hardware timer directly.