Skip to content

Latest commit

 

History

History
308 lines (240 loc) · 9.88 KB

tables.rst

File metadata and controls

308 lines (240 loc) · 9.88 KB
Raw

Tables

Tables can present complex information in an understandable way. With reStructuredText syntax, you can create tables in the following formats:

This document covers the syntax for all table formats and their pros and cons, so that you can choose the best fit for your use scenario. For more detailed instructions, please refer to reStructuredText Directives > Tables.

Simple Table

Simple tables are preceded and ended with a sequence of = to indicate columns.

Texts in the same column should be aligned with = on the left, and not extend beyond = on the right.

Simple tables supports:

  • Column span: Cells in multiple columns (except last row) can be merged by adding a sequence of -
  • Table notes: Manually numbered footnote [1]_ and autonumbered footnote [#]
  • Insert pictures
.. table::
  :align: center

  ==================================   ============================
  ESP-Docs 用户指南
  -----------------------------------------------------------------
  ==================================   ============================
  |write-doc|                          |build-doc|
  Writing Documentation [1]_           Building Documentation [#]_
  Covers ESP-Docs supported syntax     介绍如何预览、构建文档
  ==================================   ============================

.. |write-doc| image:: ../../_static/writing-documentation.png
            :height: 100px
            :width: 100px
.. |build-doc| image:: ../../_static/building-documentation.png
            :height: 100px
            :width: 100px

.. [1] This is a manually numbered table note. Note that it generates links from notes back to the table.
.. [#] This is an autonumbered table note. It generates no backlinks and continues numbering from the previous note.

The above table would be rendered as:

ESP-Docs 用户指南
   
write-doc build-doc
Writing Documentation [1] Building Documentation [2]
Covers ESP-Docs supported syntax 介绍如何预览、构建文档
[1]This is a manually numbered table note. Note that it generates links from notes back to the table.
[2]This is an autonumbered table note. It generates no backlinks and continues numbering from the previous note.

Grid Table

Grid tables are named after its grid structure formed by delimiters +, -, and |.

Grid tables support:

  • Column span
  • Row span
  • Table notes
  • Bullet Lists
  • Insert pictures (For example, see :doc:`../index`)

If there are Chinese characters, the vertical bars | can hardly be aligned to form a grid.

.. table::
  :align: center

+----------+----------------------------------------+--------------------------+
| 芯片     | 描述                                   | Ambient Temperature [#]_ |
|          |                                        +-------------+------------+
|          |                                        | Min (°C)    | Max (°C)   |
+==========+========================================+=============+============+
| ESP32-C3 | ESP32-C3 is a single-core, 32-bit,     | -40         | 105        |
|          | RISC-V-based MCU with 400 KB of SRAM,  |             |            |
|          | which is capable of running at 160 MHz.|             |            |
+----------+----------------------------------------+-------------+------------+
| ESP32-S3 | ESP32-S3 is a dual-core XTensa LX7 MCU,| -40         | 105        |
|          | capable of running at 240 MHz.         |             |            |
+----------+----------------------------------------+-------------+------------+

.. [#] This is an autonumbered table note. Note that the automatic numbering continues from the previous table note.

The above table would be rendered as:

芯片 描述 Ambient Temperature [3]
Min (°C) Max (°C)
ESP32-C3 ESP32-C3 is a single-core, 32-bit, RISC-V-based MCU with 400 KB of SRAM, which is capable of running at 160 MHz. -40 105
ESP32-S3 ESP32-S3 is a dual-core Xtensa LX7 MCU, capable of running at 240 MHz. -40 105
[3]This is an autonumbered table note. Note that the automatic numbering continues from the previous table note.

To facilitate the generation of grid tables, you may use tools such as Tables Generator.

List Table

List tables are formed of two-level lists, where the first level * represents rows, and the second level - represents columns.

The number of columns must be consistent. Empty table cells should still by marked by -, even if there is no content.

List tables support:

  • Adjustable column width
  • Table notes
  • Bullet Lists
  • Insert pictures
.. list-table::
    :header-rows: 1
    :widths: 40 60
    :align: center

    * - Field
      - Value (Byte)
    * - Type (Least Significant Bit)
      - 1
    * - Frame Control (Frag)
      -
    * - 序列号
      - 1
    * - 数据长度
      - 1
    * - Data
      - * Total Content Length: 2
        * Content: ${Data Length} - 2
    * - CheckSum (Most Significant Bit) [#]_
      - 2

.. [#] This is an autonumbered table note. Note that the automatic numbering continues from the previous table note.

The above table would be rendered as:

Field Value (Byte)
Type (Least Significant Bit) 1
Frame Control (Frag)  
序列号 1
数据长度 1
Data
  • Total Content Length: 2
  • Content: ${Data Length} - 2
CheckSum (Most Significant Bit) [4] 2
[4]This is an autonumbered table note. Note that the automatic numbering continues from the previous table note.

CSV Table

CSV (comma-separated values) tables might be the choice if you want to include CSV data into your documentation. The CSV data may be:

  • placed in a separate CSV file
  • an integral part of the document

As for formatting, CSV tables only support adjustable column width.

  • Example of integrating a separate CSV file:

    .. csv-table:: Table Title
  :file: CSV file path and name
  :widths: 30, 70
  :align: center
  :header-rows: 1

  • Example of integrating CSV data as an integral part of the document:

    .. csv-table:: Ordering Information
  :header: "订购代码", "Flash Size"
  :widths: 50, 50
  :align: center

  ESP32-C3,N/A
  ESP32-C3FN4,"4 MB"
  ESP32-C3FH4,"4 MB"

    The above table would be rendered as:

    Ordering Information

    订购代码

    Flash Size

    ESP32-C3

    N/A

    ESP32-C3FN4

    4 MB

    ESP32-C3FH4

    4 MB

    Note

    Text with spaces in between should be enclosed by quotation marks, such as "4 MB".

Comparison

To summarize:

  • 👍👍👍 List tables are ideal because they achieve a balance between easy maintenance and advanced formatting features.
  • Simple tables are good choices when table cells do not contain long sentences.
  • Grid tables provide more formatting options, but they are the most difficult to maintain.
  • CSV tables are convenient to present simple data, but not friendly to text with spaces.
  Simple Table Grid Table List Table CSV Table
What you see is what you get ✅ ✅    
Easy to maintain ✅   ✅  
Friendly to Chinese characters ✅   ✅ ✅
Friendly to long text   ✅ ✅  
Adjustable table width     ✅ ✅
Row span   ✅    
Column span ✅ ✅    
Bullet points   ✅ ✅  

Still No Good Fit?

If the above table formats cannot meet your needs, consider adding new table extensions. For example, to use a list table for its easy maintenance, but with column span and row span features, you may refer to to the flat-table directive.