docs: use the "List Table" directive to generate tables

PR Closed: #1193
Graviti-AI · Jan 13, 2022 · 32a479c · 32a479c
1 parent 685aa7a
commit 32a479c
Show file tree

Hide file tree

Showing 5 changed files with 158 additions and 106 deletions.
diff --git a/docs/source/advanced_features/request_configuration.rst b/docs/source/advanced_features/request_configuration.rst
@@ -8,31 +8,35 @@ Note that the default settings can satisfy most use cases.
 
 .. _request_config_table:
 
-.. table:: Requests Configuration Tables
+.. list-table:: Requests Configuration Tables
    :widths: auto
+   :header-rows: 1
 
-   ===================== ======================================================================================
-   Variables             Description                                              
-   ===================== ======================================================================================
-   max_retries           | The number of maximum retry times of the request.
-                         | If the request method is one of the allowed_retry_methods
-                         | and the response status is one of the allowed_retry_status,
-                         | then the request can auto-retry `max_retries` times.
-                         | Scenario: Enlarge it when under poor network quality.
-                         | Default: 3 times.
-   allowed_retry_methods | The allowed methods for retrying request.
-                         | Default: ["HEAD", "OPTIONS", "POST", "PUT"]
-   allowed_retry_status  | The allowed status for retrying request.
-                         | Default: [429, 500, 502, 503, 504]
-   timeout               | The number of seconds before the request times out.
-                         | Scenario: Enlarge it when under poor network quality.
-                         | Default: 30 seconds.
-   is_internal           | Whether the request is from internal or not. 
-                         | Scenario: Set it to True for quicker network speed when datasets
-                         | and cloud servers are in the same region.
-                         | See :doc:`/advanced_features/use_internal_endpoint` for details.
-                         | Default: False
-   ===================== ======================================================================================
+   * - Variables
+     - Description
+   * - max_retries
+     - | The number of maximum retry times of the request.
+       | If the request method is one of the allowed_retry_methods
+       | and the response status is one of the allowed_retry_status,
+       | then the request can auto-retry `max_retries` times.
+       | Scenario: Enlarge it when under poor network quality.
+       | Default: 3 times.
+   * - allowed_retry_methods
+     - | The allowed methods for retrying request.
+       | Default: ["HEAD", "OPTIONS", "POST", "PUT"]
+   * - allowed_retry_status
+     - | The allowed status for retrying request.
+       | Default: [429, 500, 502, 503, 504]
+   * - timeout
+     - | The number of seconds before the request times out.
+       | Scenario: Enlarge it when under poor network quality.
+       | Default: 30 seconds.
+   * - is_internal
+     - | Whether the request is from internal or not. 
+       | Scenario: Set it to True for quicker network speed when datasets
+       | and cloud servers are in the same region.
+       | See :doc:`/advanced_features/use_internal_endpoint` for details.
+       | Default: False
 
 Usage
 =====

diff --git a/docs/source/quick_start/examples/index.rst b/docs/source/quick_start/examples/index.rst
@@ -6,39 +6,48 @@ The following table lists a series of examples to help developers to use TensorB
 
 .. _examples_table:
 
-.. table:: Examples
+.. list-table:: Examples
    :widths: auto
+   :header-rows: 1
 
-   ====================================================================== =========================================================================
-   Examples                                                               Description
-   ====================================================================== =========================================================================
-   :doc:`/quick_start/examples/DogsVsCats`                                | Topic: Dataset Management
-                                                                          | Data Type: Image
-                                                                          | Label Type: :doc:`/reference/label_format/Classification`
-   :doc:`/quick_start/examples/Newsgroups20`                              | Topic: Dataset Management
-                                                                          | Data Type: Text
-                                                                          | Label Type: :doc:`/reference/label_format/Classification`
-   :doc:`/quick_start/examples/BSTLD`                                     | Topic: Dataset Management
-                                                                          | Data Type: Image
-                                                                          | Label Type: :doc:`/reference/label_format/Box2D`
-   :doc:`/quick_start/examples/NeolixOD`                                  | Topic: Dataset Management
-                                                                          | Data Type: Point Cloud
-                                                                          | Label Type: :doc:`/reference/label_format/Box3D`
-   :doc:`/quick_start/examples/LeedsSportsPose`                           | Topic: Dataset Management
-                                                                          | Data Type: Image
-                                                                          | Label Type: :doc:`/reference/label_format/Keypoints2D`
-   :doc:`/quick_start/examples/THCHS30`                                   | Topic: Dataset Management
-                                                                          | Data Type: Audio
-                                                                          | Label Type: :doc:`/reference/label_format/Sentence`
-   :doc:`/quick_start/examples/VOC2012Segmentation`                       | Topic: Dataset Management
-                                                                          | Data Type: Image
-                                                                          | Label Types: :doc:`/reference/label_format/SemanticMask`,
-                                                                            :doc:`/reference/label_format/InstanceMask`
-   :doc:`/quick_start/examples/update_dataset`                            | Topic: Update Dataset
-   :doc:`/quick_start/examples/move_and_copy`                             | Topic: Move And Copy
-   :doc:`/quick_start/examples/merge_datasets`                            | Topic: Merge Datasets
-   :doc:`/quick_start/examples/get_label_statistics`                      | Topic: Get Label Statistics
-   ====================================================================== =========================================================================
+   * - Examples
+     - Description
+   * - :doc:`/quick_start/examples/DogsVsCats`
+     - | Topic: Dataset Management
+       | Data Type: Image
+       | Label Type: :doc:`/reference/label_format/Classification`
+   * - :doc:`/quick_start/examples/Newsgroups20`
+     - | Topic: Dataset Management
+       | Data Type: Text
+       | Label Type: :doc:`/reference/label_format/Classification`
+   * - :doc:`/quick_start/examples/BSTLD`
+     - | Topic: Dataset Management
+       | Data Type: Image
+       | Label Type: :doc:`/reference/label_format/Box2D`
+   * - :doc:`/quick_start/examples/NeolixOD`
+     - | Topic: Dataset Management
+       | Data Type: Point Cloud
+       | Label Type: :doc:`/reference/label_format/Box3D`
+   * - :doc:`/quick_start/examples/LeedsSportsPose`
+     - | Topic: Dataset Management
+       | Data Type: Image
+       | Label Type: :doc:`/reference/label_format/Keypoints2D`
+   * - :doc:`/quick_start/examples/THCHS30`
+     - | Topic: Dataset Management
+       | Data Type: Audio
+       | Label Type: :doc:`/reference/label_format/Sentence`
+   * - :doc:`/quick_start/examples/VOC2012Segmentation`
+     - | Topic: Dataset Management
+       | Data Type: Image
+       | Label Types: :doc:`/reference/label_format/SemanticMask`, :doc:`/reference/label_format/InstanceMask`
+   * - :doc:`/quick_start/examples/update_dataset`
+     - Topic: Update Dataset
+   * - :doc:`/quick_start/examples/move_and_copy`
+     - Topic: Move And Copy
+   * - :doc:`/quick_start/examples/merge_datasets`
+     - Topic: Merge Datasets
+   * - :doc:`/quick_start/examples/get_label_statistics`
+     - Topic: Get Label Statistics
 
 .. toctree::
    :hidden:

diff --git a/docs/source/reference/dataset_structure.rst b/docs/source/reference/dataset_structure.rst
@@ -56,24 +56,27 @@ Here are some catalog examples of datasets with different label types and a data
 
 .. _catalogs_table:
 
-.. table:: Catalogs
-   :align: center
+.. list-table:: Catalogs
    :widths: auto
-
-   =============================  ============================================================================================
-    Catalogs                       Description
-   =============================  ============================================================================================
-   `elpv Catalog`_                | This example is the catalog of `elpv Dataset`_,
-                                  | which is a dataset with :doc:`/reference/label_format/Classification` label.
-   `BSTLD Catalog`_               | This example is the catalog of `BSTLD Dataset`_,
-                                  | which is a dataset with :doc:`/reference/label_format/Box2D` label.
-   `Neolix OD Catalog`_           | This example is the catalog of `Neolix OD Dataset`_,
-                                  | which is a dataset with :doc:`/reference/label_format/Box3D` label.
-   `Leeds Sports Pose Catalog`_   | This example is the catalog of `Leeds Sports Pose Dataset`_,
-                                  | which is a dataset with :doc:`/reference/label_format/Keypoints2D` label.
-   `NightOwls Catalog`_           | This example is the catalog of `NightOwls Dataset`_,
-                                  | which is a dataset with tracking :doc:`/reference/label_format/Box2D` label.
-   =============================  ============================================================================================
+   :header-rows: 1
+
+   * - Catalogs
+     - Description
+   * - `elpv Catalog`_
+     - | This example is the catalog of `elpv Dataset`_,
+       | which is a dataset with :doc:`/reference/label_format/Classification` label.
+   * - `BSTLD Catalog`_
+     - | This example is the catalog of `BSTLD Dataset`_,
+       | which is a dataset with :doc:`/reference/label_format/Box2D` label.
+   * - `Neolix OD Catalog`_
+     - | This example is the catalog of `Neolix OD Dataset`_,
+       | which is a dataset with :doc:`/reference/label_format/Box3D` label.
+   * - `Leeds Sports Pose Catalog`_
+     - | This example is the catalog of `Leeds Sports Pose Dataset`_,
+       | which is a dataset with :doc:`/reference/label_format/Keypoints2D` label.
+   * - `NightOwls Catalog`_
+     - | This example is the catalog of `NightOwls Dataset`_,
+       | which is a dataset with tracking :doc:`/reference/label_format/Box2D` label.
 
 .. _elpv Catalog: https://github.com/Graviti-AI/tensorbay-python-sdk/blob/main/tensorbay/opendataset/Elpv/catalog.json
 .. _elpv Dataset: https://gas.graviti.cn/dataset/data-decorators/Elpv

diff --git a/docs/source/reference/label_format/index.rst b/docs/source/reference/label_format/index.rst
@@ -11,26 +11,52 @@ And each type of :class:`label <~tensorbay.label.label.Label>` is supported with
 class,
 and has a corresponding :ref:`subcatalog <reference/dataset_structure:Catalog>` class.
 
-.. table:: supported label types
+.. list-table:: supported label types
    :widths: auto
+   :header-rows: 1
 
-   ============================================================= ===============================================================  =======================================================================
-   supported label types                                         label classes                                                    subcatalog classes
-   ============================================================= ===============================================================  =======================================================================
-   :doc:`/reference/label_format/Classification`                 :class:`~tensorbay.label.label_classification.Classification`    :class:`~tensorbay.label.label_classification.ClassificationSubcatalog`
-   :doc:`/reference/label_format/Box2D`                          :class:`~tensorbay.label.label_box.LabeledBox2D`                 :class:`~tensorbay.label.label_box.Box2DSubcatalog`
-   :doc:`/reference/label_format/Box3D`                          :class:`~tensorbay.label.label_box.LabeledBox3D`                 :class:`~tensorbay.label.label_box.Box3DSubcatalog`
-   :doc:`/reference/label_format/Keypoints2D`                    :class:`~tensorbay.label.label_keypoints.LabeledKeypoints2D`     :class:`~tensorbay.label.label_keypoints.Keypoints2DSubcatalog`
-   :doc:`/reference/label_format/Polygon`                        :class:`~tensorbay.label.label_polygon.LabeledPolygon`           :class:`~tensorbay.label.label_polygon.PolygonSubcatalog`
-   :doc:`/reference/label_format/MultiPolygon`                   :class:`~tensorbay.label.label_polygon.LabeledMultiPolygon`      :class:`~tensorbay.label.label_polygon.MultiPolygonSubcatalog`
-   :doc:`/reference/label_format/RLE`                            :class:`~tensorbay.label.label_polygon.LabeledRLE`               :class:`~tensorbay.label.label_polygon.RLESubcatalog`
-   :doc:`/reference/label_format/Polyline2D`                     :class:`~tensorbay.label.label_polyline.LabeledPolyline2D`       :class:`~tensorbay.label.label_polyline.Polyline2DSubcatalog`
-   :doc:`/reference/label_format/MultiPolyline2D`                :class:`~tensorbay.label.label_polyline.LabeledMultiPolyline2D`  :class:`~tensorbay.label.label_polyline.MultiPolyline2DSubcatalog`
-   :doc:`/reference/label_format/Sentence`                       :class:`~tensorbay.label.label_sentence.LabeledSentence`         :class:`~tensorbay.label.label_sentence.SentenceSubcatalog`
-   :doc:`/reference/label_format/SemanticMask`                   :class:`~tensorbay.label.label_mask.SemanticMask`                :class:`~tensorbay.label.label_mask.SemanticMaskSubcatalog`
-   :doc:`/reference/label_format/InstanceMask`                   :class:`~tensorbay.label.label_mask.InstanceMask`                :class:`~tensorbay.label.label_mask.InstanceMaskSubcatalog`
-   :doc:`/reference/label_format/PanopticMask`                   :class:`~tensorbay.label.label_mask.PanopticMask`                :class:`~tensorbay.label.label_mask.PanopticMaskSubcatalog`
-   ============================================================= ===============================================================  =======================================================================
+   * - supported label types
+     - label classes
+     - subcatalog classes
+   * - :doc:`/reference/label_format/Classification`
+     - :class:`~tensorbay.label.label_classification.Classification`
+     - :class:`~tensorbay.label.label_classification.ClassificationSubcatalog`
+   * - :doc:`/reference/label_format/Box2D`
+     - :class:`~tensorbay.label.label_box.LabeledBox2D`
+     - :class:`~tensorbay.label.label_box.Box2DSubcatalog`
+   * - :doc:`/reference/label_format/Box3D`
+     - :class:`~tensorbay.label.label_box.LabeledBox3D`
+     - :class:`~tensorbay.label.label_box.Box3DSubcatalog`
+   * - :doc:`/reference/label_format/Keypoints2D`
+     - :class:`~tensorbay.label.label_keypoints.LabeledKeypoints2D`
+     - :class:`~tensorbay.label.label_keypoints.Keypoints2DSubcatalog`
+   * - :doc:`/reference/label_format/Polygon`
+     - :class:`~tensorbay.label.label_polygon.LabeledPolygon`
+     - :class:`~tensorbay.label.label_polygon.PolygonSubcatalog`
+   * - :doc:`/reference/label_format/MultiPolygon`
+     - :class:`~tensorbay.label.label_polygon.LabeledMultiPolygon`
+     - :class:`~tensorbay.label.label_polygon.MultiPolygonSubcatalog`
+   * - :doc:`/reference/label_format/RLE`
+     - :class:`~tensorbay.label.label_polygon.LabeledRLE`
+     - :class:`~tensorbay.label.label_polygon.RLESubcatalog`
+   * - :doc:`/reference/label_format/Polyline2D`
+     - :class:`~tensorbay.label.label_polyline.LabeledPolyline2D`
+     - :class:`~tensorbay.label.label_polyline.Polyline2DSubcatalog`
+   * - :doc:`/reference/label_format/MultiPolyline2D`
+     - :class:`~tensorbay.label.label_polyline.LabeledMultiPolyline2D`
+     - :class:`~tensorbay.label.label_polyline.MultiPolyline2DSubcatalog`
+   * - :doc:`/reference/label_format/Sentence`
+     - :class:`~tensorbay.label.label_sentence.LabeledSentence`
+     - :class:`~tensorbay.label.label_sentence.SentenceSubcatalog`
+   * - :doc:`/reference/label_format/SemanticMask`
+     - :class:`~tensorbay.label.label_mask.SemanticMask`
+     - :class:`~tensorbay.label.label_mask.SemanticMaskSubcatalog`
+   * - :doc:`/reference/label_format/InstanceMask`
+     - :class:`~tensorbay.label.label_mask.InstanceMask`
+     - :class:`~tensorbay.label.label_mask.InstanceMaskSubcatalog`
+   * - :doc:`/reference/label_format/PanopticMask`
+     - :class:`~tensorbay.label.label_mask.PanopticMask`
+     - :class:`~tensorbay.label.label_mask.PanopticMaskSubcatalog`
 
 .. toctree::
    :hidden:

diff --git a/docs/source/tensorbay_cli/cli_commands.rst b/docs/source/tensorbay_cli/cli_commands.rst
@@ -6,24 +6,34 @@ The following table lists the currently supported CLI commands.(:numref:`Table.
 
 .. _cli_commands_table:
 
-.. table:: CLI Commands
+.. list-table:: CLI Commands
    :widths: auto
-
-   =======================================================  ===========================================================
-   Commands                                                 Description
-   =======================================================  ===========================================================
-   :ref:`tensorbay_cli/cli_commands:gas auth`               authentication operations.
-   :ref:`tensorbay_cli/cli_commands:gas config`             config operations
-   :ref:`tensorbay_cli/cli_commands:gas dataset`            dataset operations.
-   :ref:`tensorbay_cli/cli_commands:gas ls`                 list operations.
-   :ref:`tensorbay_cli/cli_commands:gas cp`                 copy operations.
-   :ref:`tensorbay_cli/cli_commands:gas rm`                 remove operations.
-   :ref:`tensorbay_cli/cli_commands:gas draft`              draft operations.
-   :ref:`tensorbay_cli/cli_commands:gas commit`             commit operations.
-   :ref:`tensorbay_cli/cli_commands:gas tag`                tag operations.
-   :ref:`tensorbay_cli/cli_commands:gas log`                log operations.
-   :ref:`tensorbay_cli/cli_commands:gas branch`             branch operations
-   =======================================================  ===========================================================
+   :header-rows: 1
+
+   * - Commands
+     - Description
+   * - :ref:`tensorbay_cli/cli_commands:gas auth`
+     - authentication operations.
+   * - :ref:`tensorbay_cli/cli_commands:gas config`
+     - config operations
+   * - :ref:`tensorbay_cli/cli_commands:gas dataset`
+     - dataset operations.
+   * - :ref:`tensorbay_cli/cli_commands:gas ls`
+     - list operations.
+   * - :ref:`tensorbay_cli/cli_commands:gas cp`
+     - copy operations.
+   * - :ref:`tensorbay_cli/cli_commands:gas rm`
+     - remove operations.
+   * - :ref:`tensorbay_cli/cli_commands:gas draft`
+     - draft operations.
+   * - :ref:`tensorbay_cli/cli_commands:gas commit`
+     - commit operations.
+   * - :ref:`tensorbay_cli/cli_commands:gas tag`
+     - tag operations.
+   * - :ref:`tensorbay_cli/cli_commands:gas log`
+     - log operations.
+   * - :ref:`tensorbay_cli/cli_commands:gas branch`
+     - branch operations
 
 **********
  gas auth