ESP-IDF Programming Guide
reStructuredText Syntax
» Training
reStructuredText Syntax Training
This training covers some basic reST and Sphinx syntax. To avoid warnings when building this reST file to
HTML, put it in folder esp-idf/docs/en .
Inline Formatting
Italic
Bold
Literal
Title and Heading
List
Bulleted List
Numbered List
Nested List
Table
List Table
Grid Table
Simple Table
Image
Code Block
Simple Code Block
Bash Code Block
Python Code Block
none Code Block
Link
External Link
Internal Link
Table of Contents
Index File
References
Inline Formatting
Italic
Syntax:
*text*
Rendering:
text
Bold
Syntax:
**text**
Rendering:
text
Literal
Syntax:
``code``
Rendering:
code
Note:
Use it to indicate code, user interface text, etc.
Title and Heading
# with overline, for parts
* with overline, for chapters (eg. api-reference/index.rst)
= , for sections (e.g. api-reference/api-conventions.rst)
- , for subsections
^ , for subsubsections
" , for paragraphs
List
Bulleted List
Numbered List
Nested List
Bulleted List
Syntax and example:
- Each bullet item starts with a symbol and a space.
- The symbol can be ``-``, ``*``, ``+``, etc.
Rendering:
Each bullet item starts with a symbol and a space.
The symbol can be - , * , + , etc.
Numbered List
1. Common numbered list
Syntax and example:
1. Each numbered list item starts with a symbol, a dot, and a space.
2. The symbol can be 1, A, i, (1) and so on.
Rendering:
1. Each numbered list item starts with a symbol, a dot, and a space.
2. The symbol can be 1, A, i, (1) and so on.
2. Automatic numbered list
Syntax and example:
#. Each automatic numbered list item starts with the number sign (#), a dot, and a space.
#. The number sign is #.
Rendering:
1. Each automatic numbered list item starts with the number sign (#), a dot, and a space.
2. The number sign is #.
Nested List
Example:
- This is the first item of the bulleted list.
- This is the second item of the bulleted list.
1. This is the first item of the numbered list.
2. This is the second item of the numbered list.
- This is the third item of the bulleted list.
Rendering:
This is the first item of the bulleted list.
This is the second item of the bulleted list.
1. This is the first item of the numbered list.
2. This is the second item of the numbered list.
This is the third item of the bulleted list.
Note:
1. Separate different levels of list items with a line.
2. The same level of list items should have the same indentation.
Table
List Table
Grid Table
Simple Table
List Table
Syntax:
.. list-table:: Title
:widths: 25 25 50
:header-rows: 1
* - Heading row 1, column 1
- Heading row 1, column 2
- Heading row 1, column 3
* - Row 1, column 1
-
- Row 1, column 3
* - Row 2, column 1
- Row 2, column 2
- Row 2, column 3
Rendering:
Title
Heading row 1, column 1 Heading row 1, column 2 Heading row 1, column 3
Row 1, column 1 Row 1, column 3
Row 2, column 1 Row 2, column 2 Row 2, column 3
Notes:
Title : title of the table. Optional.
:widths: : integer [integer…] or “auto”. A comma- or space-separated list of relative column widths.
The default is equal-width columns (100%/#columns). The special value “auto” may be used by writers
to decide whether to delegate the determination of column widths to the backend (LaTeX, the HTML
browser, …).
:header-rows: : integer. The number of rows of list data to use in the table header. Defaults to 0.
:stub-columns: : integer. The number of table columns to use as stubs (row titles, on the left). Defaults
to 0.
If you want an empty cell, keep the hyphen and don’t enter anything after it.
Grid Table
Syntax and example:
+-----+----------------------+-----------------------------------------+
| No. | A | B |
+-----+----------------------+-----------------------------------------+
| 1 | - Bulleted Item 1 | Below is some code:: |
| | - Bulleted Item 2 | |
| | | /.install.sh |
+-----+ 1. Numbered Item 1 +-----------------------------------------+
| 2 | 2. Numbered Item 2 | | This is the first line of this cell. |
| | | | This is the second line of this cell. |
+-----+----------------------+-----------------------------------------+
Rendering:
No. A B
Below is some code:
1 Bulleted Item 1 /.install.sh
Bulleted Item 2
1. Numbered Item 1
2. Numbered Item 2 This is the first line of this cell.
2 This is the second line of this cell.
Pros:
Can express more complex tables
merge cell
add lists, code blocks and so on
start a new line within a cell
WYSIWYG
Cons:
Time-consuming to edit
Not friendly to Chinese Characters
Note:
Try Tables Generator to generate grid tables.
Simple Table
With a header row
Syntax and example:
===== ====== ======
No. A B
===== ====== ======
1 B1
2 A2 B2
===== ====== ======
Rendering:
No. A B
1 B1
2 A2 B2
Without a header row
Syntax and example:
===== ====== ======
1 A1 B1
2 A2 B2
===== ====== ======
Rendering:
1 A1 B1
2 A2 B2
With merged cells (Follow the cells with a sequence of - to merge them)
Syntax and example:
===== ====== ======
No. Merged Cell
----- -------------
No. A B
===== ====== ======
1 Merge A1 & B1
----- -------------
2 A2 B2
3 Merge B2 & B3
===== =============
Rendering:
No. Merged Cell
No. A B
1 Merge A1 & B1
No. Merged Cell
No. A B
2 A2 B2
3 Merge B2 & B3
Pros:
Less time-consuming to edit compared to Grid format
Friendly to Chinese characters
Still WYSIWYG
Cons: Difficult to edit for long texts inside
Note:
To create a header row, wrap it with a sequence of = above and under.
To create a blank cell, just leave it empty. Row 1 and column 2 is a blank cell.
Image
Syntax:
.. figure:: ../_static/esp32-pico-devkitm-2-layout-front.png
:scale: 50 %
:align: center
:alt: ESP32-PICO-DevKitM-2 - front
:figclass: align-center
ESP32-PICO-DevKitM-2 - front
Rendering:
ESP32-PICO-DevKitM-2 - front
Note:
:scale: 50 % : integer percentage (the “%” symbol is optional). The default is “100 %”, i.e. no scaling.
../_static/esp32-pico-devkitm-2-layout-front.png : the image path. Figures are usually stored in folder
_static .
:align: center : the alignment of the image
:alt: ESP32-PICO-DevKitM-2 - front : alternate text, which is a short description of the image, displayed
by applications that cannot display images, or spoken by applications for visually impaired users.
ESP32-PICO-DevKitM-2 - front : figure caption
See Documentation Knowledge Sharing > 2022-01-20-how-to-use-figure-directive for more
information.
Some repos store source figures in different places:
ESP-IDF: idf/figures
ESP-ADF: adf/figures
ESP-AT: branch _source_figure
Code Block
Simple Code Block
Syntax and example:
::
AT+GMR
Rendering:
AT+GMR
Bash Code Block
Syntax and example:
.. code-block:: bash
ls
pwd
touch a.txt
Rendering:
ls
pwd
touch a.txt
Python Code Block
Syntax and example:
.. code-block:: python
for i in range(10):
print(i)
Rendering:
for i in range(10):
print(i)
none Code Block
If no other type applies, use “none”. It can be useful for obscure languages or mixtures of languages like
this mix of bash and python.
Syntax and example:
.. code-block:: none
cat program.py
for i in range(10):
print(i)
Rendering:
cat program.py
for i in range(10):
print(i)
Note:
Click to see more types of code blocks.
Link
External Link
An external link refers to links leading to documents outside the folder docs .
1. Regular external link
Syntax:
Welcome to `Espressif <https://www.espressif.com>`_!
Rendering:
Welcome to Espressif!
Note:
If you have several links with the same display text, it will lead to the Sphinx warning duplicate
explicit target names . To avoid this, use two underscores __ at the end of links as in the examples
above. Such links are called anonymous hyperlinks.
2. Link to code on GitHub
When linking to code on GitHub, do not use absolute/hardcoded URLs. Instead, use docutils custom roles
that will generate links for you. This is needed to ensure that links do not get broken when files in the
master branch are moved around or deleted.
Syntax and explanation:
- :project:`path` - points to directory inside project repository
- :project_file:`path` - points to file inside project repository
- :project_raw:`path` - points to raw view of the file inside project repository
- :component:`path` - points to directory inside project repository components dir
- :component_file:`path` - points to file inside project repository components dir
- :component_raw:`path` - points to raw view of the file inside project repository components dir
- :example:`path` - points to directory inside project repository examples dir
- :example_file:`path` - points to file inside project repository examples dir
- :example_raw:`path` - points to raw view of the file inside project repository examples dir
Example:
* :example:`get-started/hello_world`
* :example:`Hello World! <get-started/hello_world>`
* :example_file:`get-started/hello_world/main/hello_world_main.c`
* :example_raw:`get-started/hello_world/main/hello_world_main.c`
Rendering:
get-started/hello_world
Hello World!
get-started/hello_world/main/hello_world_main.c
get-started/hello_world/main/hello_world_main.c
Note:
See Linking Files for more information.
3. Link to parts of TRM
Syntax:
[`PDF <https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf#alias>
Example:
- For more details, see *ESP32-S2 Technical Reference Manual* > *eFuse Controller (eFuse)* [`PDF <https://www.espressif.
- See *ESP32-S2 Technical Reference Manual* > *I2C Controller (I2C)* > *Register Summary* [`PDF <https://www.espressif.c
Rendering:
For more details, see ESP32-S2 Technical Reference Manual > eFuse Controller (eFuse) [PDF].
See ESP32-S2 Technical Reference Manual > I2C Controller (I2C) > Register Summary [PDF].
Note:
See Link to Parts of PDF Using Hypertargets for details.
Only (PDF) is marked as hyperlink text, because the same documents might also be published as HTML
in the future.
Internal Link
An internal link refers to the link leading to documents within the folder docs .
1. Link to a section within the same document
Syntax and example:
`SectionName`_
`Code Block`_
Rendering:
Code Block
2. Link to other documents in the foler docs
Display the document title as the link text
Syntax: :doc:`relative path to the document you want to link to`
Example: :doc:`../get-started/index`
Rendering: Get Started
Customize the link text
Syntax: :doc:`CutomizedLinkText <relative path to the document you want to link to>`
Example: :doc:`Get Started Guide <get-started/index>`
Rendering: Get Started Guide
3. Link to a specific place of other documents in the same project
Step 1: add an anchor to the document which you want to link to, such as .. _get-started-get-
prerequisites: in the document Get Started
Step 2: insert the syntax below
Display the section name after the anchor as the link text
Syntax: :ref:`AnchorName`
Example: :ref:`get-started-get-prerequisites`
Rendering: Software
Customize the link text
Syntax: :ref:`CustomizedLinkText <AnchorName>`
Example: :ref:`Prerequisites <get-started-get-prerequisites>`
Rendering: Prerequisites
4. Link to functions, structures, and enumerators
Syntax:
- Class - :cpp:class:`name`
- Function - :cpp:func:`name`
- Structure - :cpp:type:`name`
- Structure Member - :cpp:member:`struct_name::member_name`
- Enumeration - :cpp:type:`name`
- Enumeration Value - :cpp:enumerator:`name`
Example:
- Class - :cpp:class:`esp_mqtt_client_config_t`
- Function - :cpp:func:`esp_gcov_dump`
- Structure - :cpp:type:`mesh_cfg_t`
- Structure Member - :cpp:member:`eth_esp32_emac_config_t::clock_config`
- Enumeration - :cpp:type:`esp_partition_type_t`
- Enumeration Value - :cpp:enumerator:`WIFI_MODE_APSTA`
Rendering:
Class - esp_mqtt_client_config_t
Function - esp_gcov_dump()
Structure - mesh_cfg_t
Structure Member - eth_esp32_emac_config_t::clock_config
Enumeration - esp_partition_type_t
Enumeration Value - WIFI_MODE_APSTA
Note
Marius said that some of the above declarations may change after the updates he is now doing. He will
prepare the list after the updates are done.
See Domains for more information.
Table of Contents
Syntax:
.. contents::
:local:
:depth: 1
Notes:
:depth: : integer. The number of section levels that are collected in the table of contents. The default
is unlimited depth.
:local: : Generate a local table of contents. Entries will only include subsections of the section in
which the directive is given. If no explicit title is given, the table of contents will not be titled.
Generate a table of contents (TOC) of the whole document
.. contents::
:depth: 1
Generate a TOC of a section
.. contents::
:local:
:depth: 1
Index File
Instead of using the contents directive to show a table of its own contents, the index file uses the toctree
directive to create a table of contents across files.
Syntax:
.. toctree::
:maxdepth: 2
api-conventions
protocols/index
:SOC_BT_SUPPORTED: bluetooth/index
error-codes
network/index
peripherals/index
kconfig
provisioning/index
storage/index
system/index
Rendering:
See API Reference
Note:
:maxdepth: : the maximum depth of the TOC
:hidden: : the toctree is hidden in which case they will be used to build the left navigation column but
not appear in the main page text.
References
Detailed reStructuredText and Sphinx example file
reStructuredText Directives
Sphinx/Rest Memo
reStructuredText(rst)快速⼊⻔语法说明
Quick reStructuredText
Provide feedback about this document
© Copyright 2016 - 2022, Espressif Systems (Shanghai) Co., Ltd.
Built with Sphinx using a theme based on Read the Docs Sphinx Theme. Download
PDF
