Skip to content

Commit e3552d9

Browse files
graczhualgraczhual
committed
docs: use template to generate rst files in "Examples"
1 parent d0c758b commit e3552d9

17 files changed

Lines changed: 305 additions & 961 deletions

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,10 @@ instance/
7171
# Sphinx documentation
7272
docs/_build/
7373

74+
# Documentation generated files
75+
docs/source/quick_start/examples/generated/
76+
docs/source/reference/api/api_rst/
77+
7478
# PyBuilder
7579
target/
7680

‎docs/code/LeedsSportsPose.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,10 @@
4343
dataset = Dataset("LeedsSportsPose", gas)
4444
""""""
4545

46+
"""Read Dataset / list segment names"""
47+
dataset.keys()
48+
""""""
49+
4650
"""Read Dataset / get segment"""
4751
segment = dataset[0]
4852
""""""

‎docs/code/NeolixOD.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,10 @@
4242
dataset = Dataset("NeolixOD", gas)
4343
""""""
4444

45+
"""Read Dataset / list segment names"""
46+
dataset.keys()
47+
""""""
48+
4549
"""Read Dataset / get segment"""
4650
segment = dataset[0]
4751
""""""

‎docs/source/__init__.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#!/usr/bin/env python3
2+
#
3+
# Copyright 2021 Graviti. Licensed under MIT License.
4+
#
5+
6+
"""Source."""

‎docs/source/_generate/__init__.py‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
#!/usr/bin/env python3
2+
#
3+
# Copyright 2021 Graviti. Licensed under MIT License.
4+
#
5+
6+
"""Generate."""
7+
8+
from docs.source._generate.generate_examples import generate_examples_rst
9+
10+
__all__ = ["generate_examples_rst"]

‎docs/source/_generate/generate_examples.py‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
#!/usr/bin/env python3
2+
#
3+
# Copyright 2021 Graviti. Licensed under MIT License.
4+
#
5+
"""Generate rst flies in Examples."""
6+
7+
import os
8+
import sys
9+
from collections import defaultdict
10+
from pathlib import Path
11+
12+
sys.path.insert(0, str(Path(__file__).parents[3]))
13+
from docs.source._templates import ( # noqa: E402 # pylint: disable=wrong-import-position
14+
EXAMPLES_TEMPLATE,
15+
)
16+
17+
_DATASET_NAMES = (
18+
"Dogs Vs Cats",
19+
"20 Newsgroups",
20+
"BSTLD",
21+
"Neolix OD",
22+
"Leeds Sports Pose",
23+
"THCHS-30",
24+
)
25+
_LABEL_TYPES = (
26+
"Classification",
27+
"Classification",
28+
"Box2D",
29+
"Box3D",
30+
"Keypoints2D",
31+
"Sentence",
32+
)
33+
_FILE_NAMES = ("DogsVsCats", "Newsgroups20", "BSTLD", "NeolixOD", "LeedsSportsPose", "THCHS30")
34+
35+
_DATASET_WITH_IMAGES = ("BSTLD", "Neolix OD", "Leeds Sports Pose")
36+
37+
_FIGURE_DESCRIPTION = """(:numref:`Fig. %s <example-{file_name}>`).
38+
39+
.. _example-{file_name}:
40+
41+
.. figure:: ../../../images/example-{label_type}.png
42+
:scale: 50 %
43+
:align: center
44+
45+
The preview of a cropped image with labels from "{dataset_name}".
46+
"""
47+
48+
_CATEGORY_ATTRIBUTE_DESCRIPTIONS = {}
49+
_CATEGORY_ATTRIBUTE_DESCRIPTIONS[
50+
"BSTLD"
51+
] = """
52+
The only annotation type for "{dataset_name}" is
53+
:ref:`reference/label_format/{label_type}:{label_type}`, and there are 13
54+
:ref:`reference/label_format/CommonLabelProperties:category` types and one
55+
:ref:`reference/label_format/CommonLabelProperties:attributes` type.
56+
"""
57+
58+
_CATEGORY_ATTRIBUTE_DESCRIPTIONS[
59+
"Dogs Vs Cats"
60+
] = """
61+
The only annotation type for "{dataset_name}" is
62+
:ref:`reference/label_format/{label_type}:{label_type}`, and there are 2
63+
:ref:`reference/label_format/CommonLabelProperties:category` types.
64+
"""
65+
66+
_CATEGORY_ATTRIBUTE_DESCRIPTIONS[
67+
"Leeds Sports Pose"
68+
] = """
69+
The only annotation type for "{dataset_name}" is
70+
:ref:`reference/label_format/{label_type}:{label_type}`.
71+
"""
72+
73+
_CATEGORY_ATTRIBUTE_DESCRIPTIONS[
74+
"Neolix OD"
75+
] = """
76+
The only annotation type for "{dataset_name}" is
77+
:ref:`reference/label_format/{label_type}:{label_type}`, and there are 15
78+
:ref:`reference/label_format/CommonLabelProperties:category` types and 3
79+
:ref:`reference/label_format/CommonLabelProperties:attributes` type.
80+
"""
81+
82+
_CATEGORY_ATTRIBUTE_DESCRIPTIONS[
83+
"20 Newsgroups"
84+
] = """
85+
The only annotation type for "{dataset_name}" is
86+
:ref:`reference/label_format/{label_type}:{label_type}`, and there are 20
87+
:ref:`reference/label_format/CommonLabelProperties:category` types
88+
"""
89+
90+
_CATEGORY_ATTRIBUTE_DESCRIPTIONS["THCHS-30"] = ""
91+
92+
_CATALOG_DESCRIPTIONS = defaultdict(
93+
lambda: """
94+
.. literalinclude:: ../../../../../tensorbay/opendataset/{file_name}/catalog.json
95+
:language: json
96+
:name: {file_name}-catalog
97+
:linenos:
98+
"""
99+
)
100+
101+
_CATALOG_DESCRIPTIONS[
102+
"THCHS-30"
103+
] = """However the catalog of THCHS-30 is too large, instead of
104+
reading it from json file, we read it by mapping from subcatalog that is loaded by
105+
the raw file. Check the :ref:`dataloader <THCHS30-dataloader>` below for more details.
106+
"""
107+
108+
_INFORMATION_DESCRIPTIONS = defaultdict(
109+
lambda: """The information stored in
110+
:ref:`reference/label_format/CommonLabelProperties:category` is one of the names in "categories"
111+
list of :ref:`catalog.json <{file_name}-catalog>`. The information stored in
112+
:ref:`reference/label_format/CommonLabelProperties:attributes` is one or several of
113+
the attributes in "attributes" list of :ref:`catalog.json <{file_name}-catalog>`.
114+
See :ref:`reference/label_format/{label_type}:{label_type}` label format for more details.
115+
"""
116+
)
117+
118+
_INFORMATION_DESCRIPTIONS[
119+
"THCHS-30"
120+
] = """It contains ``sentence``, ``spell`` and ``phone``
121+
information. See :ref:`Sentence <reference/label_format/{label_type}:{label_type}>` label
122+
format for more details.
123+
"""
124+
125+
126+
def generate_examples_rst(example_path: str) -> None:
127+
"""Generate rst flies in Examples.
128+
129+
Arguments:
130+
example_path: The path of rst files in Examples.
131+
132+
"""
133+
os.makedirs(example_path, exist_ok=True)
134+
for dataset_name, label_type, file_name in zip(_DATASET_NAMES, _LABEL_TYPES, _FILE_NAMES):
135+
if dataset_name in _DATASET_WITH_IMAGES:
136+
figure_description_tmp = _FIGURE_DESCRIPTION.format(
137+
dataset_name=dataset_name, file_name=file_name, label_type=label_type
138+
)
139+
else:
140+
figure_description_tmp = ""
141+
catalog_description = _CATALOG_DESCRIPTIONS[dataset_name].format(file_name=file_name)
142+
information_description = _INFORMATION_DESCRIPTIONS[dataset_name].format(
143+
label_type=label_type, file_name=file_name
144+
)
145+
category_attribute_description = _CATEGORY_ATTRIBUTE_DESCRIPTIONS[dataset_name].format(
146+
dataset_name=dataset_name, label_type=label_type
147+
)
148+
with open(os.path.join(example_path, f"{file_name}.rst"), "w", encoding="utf-8") as fp:
149+
fp.write(
150+
EXAMPLES_TEMPLATE.format(
151+
dataset_name=dataset_name,
152+
file_name=file_name,
153+
label_type=label_type,
154+
figure_description=figure_description_tmp,
155+
catalog_description=catalog_description,
156+
category_attribute_description=category_attribute_description,
157+
information_description=information_description,
158+
)
159+
)

‎docs/source/_templates/__init__.py‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
#!/usr/bin/env python3
2+
#
3+
# Copyright 2021 Graviti. Licensed under MIT License.
4+
#
5+
6+
"""Template."""
7+
8+
from docs.source._templates.examples import EXAMPLES_TEMPLATE
9+
10+
__all__ = ["EXAMPLES_TEMPLATE"]

0 commit comments

Comments
 (0)