docs: use template to generate rst files in "Examples"

Author: graczhual

docs/code/LeedsSportsPose.py

@@ -43,6 +43,10 @@
 dataset = Dataset("LeedsSportsPose", gas)
 """"""
 
+"""Read Dataset / list segment names"""
+dataset.keys()
+""""""
+
 """Read Dataset / get segment"""
 segment = dataset[0]
 """"""

docs/code/NeolixOD.py

@@ -42,6 +42,10 @@
 dataset = Dataset("NeolixOD", gas)
 """"""
 
+"""Read Dataset / list segment names"""
+dataset.keys()
+""""""
+
 """Read Dataset / get segment"""
 segment = dataset[0]
 """"""

docs/source/conf.py

@@ -15,9 +15,12 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 """Configuration file for the Sphinx documentation builder."""
+import os
 import sys
 from pathlib import Path
 
+import jinja2
+
 sys.path.insert(0, str(Path(__file__).parents[2]))
 
 
@@ -79,3 +82,34 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 # html_static_path = ["_static"]
+
+source_path = os.path.dirname(os.path.abspath(__file__))
+example_path = os.path.join(source_path, "quick_start", "examples")
+datasets = (
+    "Dogs Vs Cats",
+    "20 Newsgroups",
+    "BSTLD",
+    "Neolix OD",
+    "Leeds Sports Pose",
+    "THCHS-30",
+)
+label_types = (
+    "Classification",
+    "Classification",
+    "Box2D",
+    "Box3D",
+    "Keypoints2D",
+    "Sentence",
+)
+file_names = ("DogsVsCats", "Newsgroups20", "BSTLD", "NeolixOD", "LeedsSportsPose", "THCHS30")
+for dataset_name, label_type, file_name in zip(datasets, label_types, file_names):
+    with open(os.path.join(example_path, "examples.rst.template"), encoding="utf-8") as f:
+        t = jinja2.Template(f.read())
+    with open(os.path.join(example_path, f"{file_name}.rst"), "w", encoding="utf-8") as f:
+        f.write(
+            t.render(
+                dataset_name=dataset_name,
+                label_type=label_type,
+                file_name=file_name,
+            )
+        )

docs/source/quick_start/examples/BSTLD.rst

@@ -1,9 +1,12 @@
-########
+
+
+##################
  BSTLD
-########
+##################
 
 This topic describes how to manage the `BSTLD Dataset <https://gas.graviti.cn/dataset/data-decorators/BSTLD>`_,
-which is a dataset with :ref:`reference/label_format/Box2D:Box2D` label(:numref:`Fig. %s <example-bstld>`).
+which is a dataset with :ref:`reference/label_format/Box2D:Box2D` label
+(:numref:`Fig. %s <example-bstld>`).
 
 .. _example-bstld:
 
@@ -13,6 +16,7 @@ which is a dataset with :ref:`reference/label_format/Box2D:Box2D` label(:numref:
 
    The preview of a cropped image with labels from "BSTLD".
 
+
 *****************************
  Authorize a Client Instance
 *****************************
@@ -48,16 +52,28 @@ Step 1: Write the Catalog
 =========================
 
 A :ref:`reference/dataset_structure:catalog` contains all label information of one dataset, which
-is typically stored in a json file like ``catalog.json``.
+is typically stored in a json file like ``catalog.json``. 
+
 
 .. literalinclude:: ../../../../tensorbay/opendataset/BSTLD/catalog.json
    :language: json
    :name: BSTLD-catalog
    :linenos:
 
+
+
 The only annotation type for "BSTLD" is :ref:`reference/label_format/Box2D:Box2D`, and there are 13
 :ref:`reference/label_format/CommonLabelProperties:category` types and one :ref:`reference/label_format/CommonLabelProperties:attributes` type.
 
+
+
+
+
+
+
+
+
+
 .. note::
 
    By passing the path of the ``catalog.json``, :func:`~tensorbay.dataset.dataset.DatasetBase.load_catalog` supports loading the catalog into dataset.
@@ -114,7 +130,7 @@ The organized "BSTLD" dataset can be uploaded to TensorBay for sharing, reuse, e
    :end-before: """"""
 
 .. note::
-   Set `skip_uploaded_files=True` to skip uploaded data.
+   Set ``skip_uploaded_files=True`` to skip uploaded data.
    The data will be skiped if its name and segment name is the same as remote data.
 
 Similar with Git, the commit step after uploading can record changes to the dataset as a version.
@@ -132,8 +148,6 @@ Now "BSTLD" dataset can be read from TensorBay.
    :start-after: """Read Dataset / get dataset"""
    :end-before: """"""
 
-In :ref:`reference/dataset_structure:dataset` "BSTLD", there are three
-:ref:`segments <reference/dataset_structure:segment>`: ``train``, ``test`` and ``additional``.
 Get the segment names by listing them all.
 
 .. literalinclude:: ../../../../docs/code/BSTLD.py
@@ -148,8 +162,7 @@ Get a segment by passing the required segment name.
    :start-after: """Read Dataset / get segment"""
    :end-before: """"""
 
-
-In the train :ref:`reference/dataset_structure:segment`, there is a sequence of :ref:`reference/dataset_structure:data`,
+In the :ref:`reference/dataset_structure:segment`, there is a sequence of :ref:`reference/dataset_structure:data`,
 which can be obtained by index.
 
 .. literalinclude:: ../../../../docs/code/BSTLD.py
@@ -167,16 +180,18 @@ which can be obtained by index.
    :end-before: """"""
 
 There is only one label type in "BSTLD" dataset, which is ``box2d``.
+
 The information stored in :ref:`reference/label_format/CommonLabelProperties:category` is
 one of the names in "categories" list of :ref:`catalog.json <BSTLD-catalog>`. The information stored
 in :ref:`reference/label_format/CommonLabelProperties:attributes` is one or several of the attributes in "attributes" list of :ref:`catalog.json <BSTLD-catalog>`.
 See :ref:`reference/label_format/Box2D:Box2D` label format for more details.
 
+
 ****************
  Delete Dataset
 ****************
 
 .. literalinclude:: ../../../../docs/code/BSTLD.py
    :language: python
    :start-after: """Delete Dataset"""
-   :end-before: """"""
+   :end-before: """"""

docs/source/quick_start/examples/DogsVsCats.rst

@@ -1,9 +1,11 @@
-##############
- Dogs vs Cats
-##############
 
-This topic describes how to manage the `Dogs vs Cats Dataset <https://gas.graviti.cn/dataset/data-decorators/DogsVsCats>`_,
-which is a dataset with :ref:`reference/label_format/Classification:Classification` label.
+
+##################
+ Dogs Vs Cats
+##################
+
+This topic describes how to manage the `Dogs Vs Cats Dataset <https://gas.graviti.cn/dataset/data-decorators/DogsVsCats>`_,
+which is a dataset with :ref:`reference/label_format/Classification:Classification` label
 
 *****************************
  Authorize a Client Instance
@@ -29,27 +31,39 @@ An :ref:`reference/glossary:accesskey` is needed to authenticate identity when u
  Organize Dataset
 ******************
 
-Normally, ``dataloader.py`` and ``catalog.json`` are required to organize the "Dogs vs Cats" dataset into the :class:`~tensorbay.dataset.dataset.Dataset` instance.
+Normally, ``dataloader.py`` and ``catalog.json`` are required to organize the "Dogs Vs Cats" dataset into the :class:`~tensorbay.dataset.dataset.Dataset` instance.
 In this example, they are stored in the same directory like::
 
-    Dogs vs Cats/
+    Dogs Vs Cats/
         catalog.json
         dataloader.py
 
 Step 1: Write the Catalog
 =========================
 
 A :ref:`reference/dataset_structure:catalog` contains all label information of one dataset, which
-is typically stored in a json file like ``catalog.json``.
+is typically stored in a json file like ``catalog.json``. 
+
 
 .. literalinclude:: ../../../../tensorbay/opendataset/DogsVsCats/catalog.json
    :language: json
-   :name: dogsvscats-catalog
+   :name: DogsVsCats-catalog
    :linenos:
 
-The only annotation type for "Dogs vs Cats" is :ref:`reference/label_format/Classification:Classification`, and there are 2
+
+
+
+
+The only annotation type for "Dogs Vs Cats" is :ref:`reference/label_format/Classification:Classification`, and there are 2
 :ref:`reference/label_format/CommonLabelProperties:category` types.
 
+
+
+
+
+
+
+
 .. note::
 
    By passing the path of the ``catalog.json``, :func:`~tensorbay.dataset.dataset.DatasetBase.load_catalog` supports loading the catalog into dataset.
@@ -61,19 +75,17 @@ The only annotation type for "Dogs vs Cats" is :ref:`reference/label_format/Clas
 Step 2: Write the Dataloader
 ============================
 
-A :ref:`reference/glossary:dataloader` is needed to organize the dataset into
-a :class:`~tensorbay.dataset.dataset.Dataset` instance.
+A :ref:`reference/glossary:dataloader` is needed to organize the dataset into a :class:`~tensorbay.dataset.dataset.Dataset` instance.
 
 .. literalinclude:: ../../../../tensorbay/opendataset/DogsVsCats/loader.py
    :language: python
-   :name: dogsvscats-dataloader
+   :name: DogsVsCats-dataloader
    :linenos:
 
 See :ref:`Classification annotation <reference/label_format/Classification:Classification>` for more details.
 
-
 There are already a number of dataloaders in TensorBay SDK provided by the community.
-Thus, instead of writing, importing an available dataloadert is also feasible.
+Thus, instead of writing, importing an available dataloader is also feasible.
 
 .. literalinclude:: ../../../../docs/code/DogsVsCats.py
    :language: python
@@ -86,7 +98,7 @@ Thus, instead of writing, importing an available dataloadert is also feasible.
 
 .. important::
 
-   See :ref:`dataloader table <reference/glossary:dataloader>` for more examples of dataloaders with different label types.
+   See :ref:`dataloader table <reference/glossary:dataloader>` for dataloaders with different label types.
 
 *******************
  Visualize Dataset
@@ -100,13 +112,17 @@ Please see :ref:`features/visualization:Visualization` for more details.
  Upload Dataset
 ****************
 
-The organized "Dogs vs Cats" dataset can be uploaded to TensorBay for sharing, reuse, etc.
+The organized "Dogs Vs Cats" dataset can be uploaded to TensorBay for sharing, reuse, etc.
 
 .. literalinclude:: ../../../../docs/code/DogsVsCats.py
    :language: python
    :start-after: """Upload Dataset"""
    :end-before: """"""
 
+.. note::
+   Set ``skip_uploaded_files=True`` to skip uploaded data.
+   The data will be skiped if its name and segment name is the same as remote data.
+
 Similar with Git, the commit step after uploading can record changes to the dataset as a version.
 If needed, do the modifications and commit again.
 Please see :ref:`features/version_control/index:Version Control` for more details.
@@ -115,15 +131,13 @@ Please see :ref:`features/version_control/index:Version Control` for more detail
  Read Dataset
 **************
 
-Now "Dogs vs Cats" dataset can be read from TensorBay.
+Now "Dogs Vs Cats" dataset can be read from TensorBay.
 
 .. literalinclude:: ../../../../docs/code/DogsVsCats.py
    :language: python
    :start-after: """Read Dataset / get dataset"""
    :end-before: """"""
 
-In :ref:`reference/dataset_structure:dataset` "Dogs vs Cats", there are two
-:ref:`segments <reference/dataset_structure:segment>`: ``train`` and ``test``.
 Get the segment names by listing them all.
 
 .. literalinclude:: ../../../../docs/code/DogsVsCats.py
@@ -138,7 +152,7 @@ Get a segment by passing the required segment name.
    :start-after: """Read Dataset / get segment"""
    :end-before: """"""
 
-In the train :ref:`reference/dataset_structure:segment`, there is a sequence of :ref:`reference/dataset_structure:data`,
+In the :ref:`reference/dataset_structure:segment`, there is a sequence of :ref:`reference/dataset_structure:data`,
 which can be obtained by index.
 
 .. literalinclude:: ../../../../docs/code/DogsVsCats.py
@@ -155,15 +169,19 @@ which can be obtained by index.
    :start-after: """Read Dataset / get label"""
    :end-before: """"""
 
-There is only one label type in "Dogs vs Cats" dataset, which is ``classification``. The information stored in :ref:`reference/label_format/CommonLabelProperties:category` is
-one of the names in "categories" list of :ref:`catalog.json <dogsvscats-catalog>`.
+There is only one label type in "Dogs Vs Cats" dataset, which is ``classification``.
+
+The information stored in :ref:`reference/label_format/CommonLabelProperties:category` is
+one of the names in "categories" list of :ref:`catalog.json <DogsVsCats-catalog>`. The information stored
+in :ref:`reference/label_format/CommonLabelProperties:attributes` is one or several of the attributes in "attributes" list of :ref:`catalog.json <DogsVsCats-catalog>`.
 See :ref:`reference/label_format/Classification:Classification` label format for more details.
 
+
 ****************
  Delete Dataset
 ****************
 
 .. literalinclude:: ../../../../docs/code/DogsVsCats.py
    :language: python
    :start-after: """Delete Dataset"""
-   :end-before: """"""
+   :end-before: """"""