Skip to content

Commit ec06326

Browse files
ahalahal
committed
docs: convert schema comments into descriptions
This way they'll be rendered in the docs.
1 parent 4c48f62 commit ec06326

File tree

7 files changed

+636
-196
lines changed

7 files changed

+636
-196
lines changed

‎src/taskgraph/transforms/docker_image.py‎

Lines changed: 68 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
import logging
66
import os
77
import re
8+
from textwrap import dedent
89

910
from voluptuous import Optional, Required
1011

@@ -33,29 +34,78 @@
3334
#: Schema for docker_image transforms
3435
docker_image_schema = Schema(
3536
{
36-
# Name of the docker image.
37-
Required("name"): str,
38-
# Name of the parent docker image.
39-
Optional("parent"): str,
40-
# Treeherder symbol.
41-
Optional("symbol"): str,
42-
# relative path (from config.path) to the file the docker image was defined
43-
# in.
44-
Optional("task-from"): str,
45-
# Arguments to use for the Dockerfile.
46-
Optional("args"): {str: str},
47-
# Name of the docker image definition under taskcluster/docker, when
48-
# different from the docker image name.
49-
Optional("definition"): str,
50-
# List of package tasks this docker image depends on.
51-
Optional("packages"): [str],
37+
Required(
38+
"name",
39+
description=dedent(
40+
"""
41+
Name of the docker image.
42+
"""
43+
).lstrip(),
44+
): str,
45+
Optional(
46+
"parent",
47+
description=dedent(
48+
"""
49+
Name of the parent docker image.
50+
"""
51+
).lstrip(),
52+
): str,
53+
Optional(
54+
"symbol",
55+
description=dedent(
56+
"""
57+
Treeherder symbol.
58+
"""
59+
).lstrip(),
60+
): str,
61+
Optional(
62+
"task-from",
63+
description=dedent(
64+
"""
65+
Relative path (from config.path) to the file the docker image was defined in.
66+
"""
67+
).lstrip(),
68+
): str,
69+
Optional(
70+
"args",
71+
description=dedent(
72+
"""
73+
Arguments to use for the Dockerfile.
74+
"""
75+
).lstrip(),
76+
): {str: str},
77+
Optional(
78+
"definition",
79+
description=dedent(
80+
"""
81+
Name of the docker image definition under taskcluster/docker, when
82+
different from the docker image name.
83+
"""
84+
).lstrip(),
85+
): str,
86+
Optional(
87+
"packages",
88+
description=dedent(
89+
"""
90+
List of package tasks this docker image depends on.
91+
"""
92+
).lstrip(),
93+
): [str],
5294
Optional(
5395
"index",
54-
description="information for indexing this build so its artifacts can be discovered",
96+
description=dedent(
97+
"""
98+
Information for indexing this build so its artifacts can be discovered.
99+
"""
100+
).lstrip(),
55101
): task_description_schema["index"],
56102
Optional(
57103
"cache",
58-
description="Whether this image should be cached based on inputs.",
104+
description=dedent(
105+
"""
106+
Whether this image should be cached based on inputs.
107+
"""
108+
).lstrip(),
59109
): bool,
60110
}
61111
)

‎src/taskgraph/transforms/fetch.py‎

Lines changed: 39 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
import os
1010
import re
1111
from dataclasses import dataclass
12+
from textwrap import dedent
1213
from typing import Callable
1314

1415
from voluptuous import Extra, Optional, Required
@@ -26,25 +27,51 @@
2627
#: Schema for fetch transforms
2728
FETCH_SCHEMA = Schema(
2829
{
29-
# Name of the task.
30-
Required("name"): str,
31-
# Relative path (from config.path) to the file the task was defined
32-
# in.
33-
Optional("task-from"): str,
34-
# Description of the task.
35-
Required("description"): str,
30+
Required(
31+
"name",
32+
description=dedent(
33+
"""
34+
Name of the task.
35+
""".lstrip()
36+
),
37+
): str,
38+
Optional(
39+
"task-from",
40+
description=dedent(
41+
"""
42+
Relative path (from config.path) to the file the task was defined
43+
in.
44+
""".lstrip()
45+
),
46+
): str,
47+
Required(
48+
"description",
49+
description=dedent(
50+
"""
51+
Description of the task.
52+
""".lstrip()
53+
),
54+
): str,
3655
Optional("expires-after"): str,
3756
Optional("docker-image"): object,
3857
Optional(
3958
"fetch-alias",
40-
description="An alias that can be used instead of the real fetch task name in "
41-
"fetch stanzas for tasks.",
59+
description=dedent(
60+
"""
61+
An alias that can be used instead of the real fetch task name in
62+
fetch stanzas for tasks.
63+
""".lstrip()
64+
),
4265
): str,
4366
Optional(
4467
"artifact-prefix",
45-
description="The prefix of the taskcluster artifact being uploaded. "
46-
"Defaults to `public/`; if it starts with something other than "
47-
"`public/` the artifact will require scopes to access.",
68+
description=dedent(
69+
"""
70+
The prefix of the taskcluster artifact being uploaded.
71+
Defaults to `public/`; if it starts with something other than
72+
`public/` the artifact will require scopes to access.
73+
""".lstrip()
74+
),
4875
): str,
4976
Optional("attributes"): {str: object},
5077
Required("fetch"): {

‎src/taskgraph/transforms/from_deps.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
from copy import deepcopy
1515
from textwrap import dedent
1616

17-
from voluptuous import ALLOW_EXTRA, Any, Extra, Optional, Required
17+
from voluptuous import ALLOW_EXTRA, Any, Optional, Required
1818

1919
from taskgraph.transforms.base import TransformSequence
2020
from taskgraph.transforms.run import fetches_schema

‎src/taskgraph/transforms/run/__init__.py‎

Lines changed: 85 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111

1212
import copy
1313
import logging
14+
from textwrap import dedent
1415

1516
from voluptuous import Exclusive, Extra, Optional, Required
1617

@@ -39,13 +40,28 @@
3940
#: Schema for a run transforms
4041
run_description_schema = Schema(
4142
{
42-
# The name of the task and the task's label. At least one must be specified,
43-
# and the label will be generated from the name if necessary, by prepending
44-
# the kind.
45-
Optional("name"): str,
46-
Optional("label"): str,
43+
Optional(
44+
"name",
45+
description=dedent(
46+
"""
47+
The name of the task. At least one of 'name' or 'label' must be
48+
specified. If 'label' is not provided, it will be generated from
49+
the 'name' by prepending the kind.
50+
"""
51+
),
52+
): str,
53+
Optional(
54+
"label",
55+
description=dedent(
56+
"""
57+
The label of the task. At least one of 'name' or 'label' must be
58+
specified. If 'label' is not provided, it will be generated from
59+
the 'name' by prepending the kind.
60+
"""
61+
),
62+
): str,
4763
# the following fields are passed directly through to the task description,
48-
# possibly modified by the run implementation. See
64+
# possibly modified by the run implementation. See
4965
# taskcluster/taskgraph/transforms/task.py for the schema details.
5066
Required("description"): task_description_schema["description"],
5167
Optional("priority"): task_description_schema["priority"],
@@ -72,37 +88,80 @@
7288
"optimization"
7389
],
7490
Optional("needs-sccache"): task_description_schema["needs-sccache"],
75-
# The "when" section contains descriptions of the circumstances under which
76-
# this task should be included in the task graph. This will be converted
77-
# into an optimization, so it cannot be specified in a run description that
78-
# also gives 'optimization'.
79-
Exclusive("when", "optimization"): {
80-
# This task only needs to be run if a file matching one of the given
81-
# patterns has changed in the push. The patterns use the mozpack
82-
# match function (python/mozbuild/mozpack/path.py).
83-
Optional("files-changed"): [str],
91+
Exclusive(
92+
"when",
93+
"optimization",
94+
description=dedent(
95+
"""
96+
The "when" section contains descriptions of the circumstances under
97+
which this task should be included in the task graph. This will be
98+
converted into an optimization, so it cannot be specified in a run
99+
description that also gives 'optimization'.
100+
"""
101+
),
102+
): {
103+
Optional(
104+
"files-changed",
105+
description=dedent(
106+
"""
107+
This task only needs to be run if a file matching one of the given
108+
patterns has changed in the push. The patterns use the mozpack
109+
match function (python/mozbuild/mozpack/path.py).
110+
"""
111+
),
112+
): [str],
84113
},
85-
# A list of artifacts to install from 'fetch' tasks.
86-
Optional("fetches"): {
114+
Optional(
115+
"fetches",
116+
description=dedent(
117+
"""
118+
A list of artifacts to install from 'fetch' tasks.
119+
"""
120+
),
121+
): {
87122
str: [
88123
str,
89124
fetches_schema,
90125
],
91126
},
92-
# A description of how to run this task.
93-
"run": {
94-
# The key to a run implementation in a peer module to this one
95-
"using": str,
96-
# Base work directory used to set up the task.
97-
Optional("workdir"): str,
127+
Required(
128+
"run",
129+
description=dedent(
130+
"""
131+
A description of how to run this task.
132+
"""
133+
),
134+
): {
135+
Required(
136+
"using",
137+
description=dedent(
138+
"""
139+
The key to a run implementation in a peer module to this one.
140+
"""
141+
),
142+
): str,
143+
Optional(
144+
"workdir",
145+
description=dedent(
146+
"""
147+
Base work directory used to set up the task.
148+
"""
149+
),
150+
): str,
98151
# Any remaining content is verified against that run implementation's
99152
# own schema.
100153
Extra: object,
101154
},
102155
Required("worker-type"): task_description_schema["worker-type"],
103-
# This object will be passed through to the task description, with additions
104-
# provided by the task's run-using function
105-
Optional("worker"): dict,
156+
Required(
157+
"worker",
158+
description=dedent(
159+
"""
160+
This object will be passed through to the task description, with additions
161+
provided by the task's run-using function.
162+
"""
163+
),
164+
): dict,
106165
}
107166
)
108167

0 commit comments

Comments
 (0)