Doc Template

The main components of a document are as follows:

• Document Name

• Main Body

Document Name

Document name is the title of the document.

There are several kinds of documents:

1. User Manual

2. Application Note

3. …

Example: Tool Set User Manual.

Note

The first letter of each word in the document name needs to be capitalized, e.g. Tool Set User Manual

Main Body

Contents which are the main parts of document.

Chapter

The deepest level of a chapter number is 5. The format list is shown in the following table:

Chapter	Example	Index
First-level Heading	## Content	{#Title_1}
Second-level Heading	### Content	{#Title_2}
Third-level Heading	#### Content	{#Title_3}
Fourth-level Heading	##### Content	{#Title_4}
Fifth-level Heading	###### Content	{#Title_5}

Note

Usually, the depth level of contents is 3.

Paragraph

A blank line is required between paragraphs. When doxygen recognizes this blank line, it will consider it as a paragraph and add the paragraph interval, which is set uniformly by CSS.

Examlple:

This is a new paragraph.

<br/> command only represents line break, and doxygen will not recognize it as a paragraph.

Examlple:
This is just a new line, not a new paragraph.

List

The deepest level of a list is 3. The detailed list format is shown below.

Unordered list:

• Contents

  • Contents

  • Contents

    • Contents

    • Contents

• Contents

  • Contents

  • Contents

    • Contents

    • Contents

Ordered list:

1. Contents

   1. Contents

   2. Contents

      1. Contents

      2. Contents

2. Contents

   1. Contents

   2. Contents

      1. Contents

      2. Contents

3. Contents

   1. Contents

   2. Contents

      1. Contents

      2. Contents

Nested content in a list: Nested text, images, and tables should all be indented the same way as the corresponding level of the list.

1. Contents

   Title	Xx	Xx
   Item1	Xx	Xx
   Item2	Xx	Xx

2. Contents

3. Contents

   some text:

   code
   

   some text:

Table

Draw Table

Table using rules:

• The first word in the content of the table needs to start with a capital letter.

• The table headers are centered aligned, while the body of the table is centered-aligned or left-aligned based on the length of the content.

Example 1: Table header and table content are both ceter aligned.

Title	Xx	Xx
Item1	Xx	Xx
Item2	Xx	Xx

Example 2: Table head is center aligned and table content is left aligned.

Title	Xx	Xx
Item1	Xx	Xx
Item2	Xx	Xx

Example 3: If a complex table is needed, HTML command can be used.

Title	Title	Title
Xx	Xx	Xx
Xx		Xx
Xx	Xx	Xx
	Xx	Xx

Set Column Widths

If the width of each column in the table needs to be adjusted, the method is provided below.

For tables created using Markdown syntax:

Title	Xx	Xx
Item1	Xx	Xx
Item2	Xx	Xx

Title	Xx	Xx
Item1	Xx	Xx
Item2	Xx	Xx

Note

1. The table will be laid out according to the proportion of the width of each column, ensuring that the sum of the widths of each column does not exceed 800px.

2. Although the widths of the columns are set proportionally, it is important not to set the values too small (<50px), as it may lead to unexpected formatting issues.

3. Since the width set in a Markdown table actually refers to the width of the columns, if a column’s content is too long, setting a narrow width will result in automatic line breaks. In such cases, it is necessary to set a wider width for proper layout. Please refer to the example below.

Examlple:

The two tables below are of the same type, but the automatically generated column widths are inconsistent, which is not visually appealing. Therefore, it is necessary to manually set the column widths to achieve consistent column widths.

Value	Parameter Description
0xXX	the acked event_id

Value	Parameter Description
0x00	command complete : MCU can handle this command.
0x01	command disallow: MCU can not handle this command.
0x02	unknow CMD

If the column widths are set to 100px and 300px respectively, it will result in automatic line breaks for long fields.

Value	Parameter Description
0xXX	the acked event_id

Value	Parameter Description
0x00	command complete : MCU can handle this command.
0x01	command disallow: MCU can not handle this command.
0x02	unknow CMD

If the column widths are set to 100px and 600px respectively, the desired effect can be achieved.

Value	Parameter Description
0xXX	the acked event_id

Value	Parameter Description
0x00	command complete : MCU can handle this command.
0x01	command disallow: MCU can not handle this command.
0x02	unknow CMD

For tables created using HTML syntax:

Title	Title	Title
Xx	Xx	Xx
Xx		Xx
Xx	Xx	Xx
	Xx	Xx

Note

The sum of the widths of each column should be 100%.

Figure

Figure using rules:

• see figure template in HoneyComb\sdk\doc\vsd\sample

Example:

If the size of the figure needs to be adjusted, the method is provided below.

Note

The adjusted proportion is not relative to the original size of the figure, but relative to the parent container of the figure.

Emphasis

Italic and bold can be used to emphasize certain content. To italicize a text fragment, you can start and end the fragment with an underscore by Markdown command.

Example:

single underscores

To bold a text fragment, you can use two underscores by Markdown command.

Example:

double underscores

Block Quotes

Block quotes can be created by starting each line with one or more >’s. Note that doxygen requires that a space is put after the (last) > character to avoid false positives. This format can be used for supplementary explanations.

Examples:

This is a block quote spanning multiple lines

Lists and code blocks can appear inside a quote block.

Quotes:

1. Some text

2. Some text

Quote blocks can also be nested.

Some text

Some text

Some text

Note and Warning

Note

If some notes need to be emphasized, the Admonition extension can be used to generate prompt code blocks. The syntax is as follows:

Note

This is a note.

To make the expression clearer, it is recommended that each prompt statement should not be too long. When there is a lot of prompt content, it can be in the form of a list.

Examples:

Note

1. Note1

2. Note2

Warning

The methods of warning and note are basically the same. The syntax is as follows:

Warning

This is a warning.

References

When guiding users to refer to other documents or code, it is necessary to cite references.

Document References

You can use the [Click here to some specified documents](#id) command to link to the corresponding document.

Note

ID must be unique.

• If a specified chapter is cited, please follow the syntax in Example 1.

  Example 1: Please refer to Download Mode for more details.

• If a specified document is cited, please follow the syntax in Example 2.

  Example 2: Please refer to Quick Start User Guide for more details.

• If a specified table or figure is cited, please follow the syntax in Example 3.

  Example 3: Please refer to Example Table and Example Figure for more details.

Note

When referencing an image or a table, it is necessary to insert the unique ID before the image or table that you want to refer to. e.g. {#Doc_Template_table_example} or {#Doc_Template_figure_example}

Since Markdown command does not work within HTML tables, if you need to create links within an HTML table, the following specific HTML commands should be used to achieve redirection.

Command	Description	ACI Command
connect headset_sample	Connect to a bud with a specific addr	ACI_CMD_BT_CREATE_CONNECTION
connect idx	Need inquiry first, select an index, connect to that bud
connect phone_sample	Connect to a phone with a specific address
disconnect headset_sample	Disconnect bud	ACI_CMD_BT_DISCONNECT
disconnect phone_sample	Disconnect phone

Note

1. Confirm that the relative path of the href jump link is correct.

2. Use lowercase for anchor points and connect words with a hyphen (“-“).

Code References

You can use the [Click here to some specified codes](#id) command to link to the corresponding code.

Example:

• Macro: SITRONIX_SECP_INDEX

• Struct: struct t_dual_audio_pos

• Function: app_dual_audio_effect_spp_init(uint16_t offset_44K, uint8_t app_idx)

Glossary References

After adding terms in sdk\doc\text\Glossary.rst in the given format, you can use [TERM](/text/Glossary.rst#term-TERM) command to link to the corresponding term in the glossary at the abbreviation in the main text.

Example:

Users can compile all the applications in the SDK using the Keil MDK. The purpose of this document is to provide an overview of Bluetooth BR/EDR Stack APIs.

Adding Code

Code Spans

Unlike code blocks, code spans appear inline in a paragraph.

• To indicate a span of code that requires a link, the following syntax needs to be used.

  Example: Use the app_dual_audio_effect_reset() function.

• To indicate a span of code that does not require a link, you should wrap it in backticks.

  Example: Use the printf() function.

• To show a literal backtick or single quote inside a code span, double backticks can be used.

  Example: To assign the text ‘text’ to var use var='text'.

Code Blocks

A pair of “fence lines” defines a fenced code block. For languages supported by doxygen you can also make the code block appear with syntax highlighting. To do so you need to indicate the typical file extension that corresponds to the programming language after the opening fence.

Example:

/* This function executed in idle task, place in ram for power saving */
APP_FLASH_RAM_TEXT_SECTION bool app_dlps_check_callback(void)
{
    if ((app_cfg_const.enable_dlps) && (dlps_bitmap == 0))
    {
        return true;
    }
    else
    {
        return false;
    }
}

void app_dlps_init(void)
{
    /* Register inquiry callback function to DLPS Framework, and this function will be called each
       time before entering DLPS to decide whether DLPS is allowed to enter.
       DLPS would be disallowed if any inquiry callback function returns FALSE. */
    if (power_check_cb_register(app_dlps_check_callback) == false)
    {
        APP_PRINT_ERROR0("app_dlps_init: dlps_check_cb_reg failed");
    }

    /* DLPS_IO_EnterDlpsCb would be always registered in application sample project, and the callback function is used to save generic peripheral registers when entering DLPS mode.
    The storage actions of app-specific peripherals need to be encapsulated into function and registered through this API */
    DLPS_IORegUserDlpsEnterCb(app_dlps_enter_callback);

    /* the callback function is used to save generic peripheral registers when exiting from DLPS       and to process App-specific peripheral recovery.
      The recovery actions of app-specific peripheral need to be encapsulated into function and registered through this API. */
    DLPS_IORegUserDlpsExitCb(app_dlps_exit_callback);
}

The above is a code block.