Convert schema comments to descriptions

src/taskgraph/config.py

@@ -9,7 +9,7 @@
 from dataclasses import dataclass
 from typing import Dict
 
-from voluptuous import All, Any, Extra, Length, Optional, Required
+from voluptuous import ALLOW_EXTRA, All, Any, Extra, Length, Optional, Required
 
 from .util import path
 from .util.caches import CACHES
@@ -101,8 +101,8 @@
                 Length(min=1),
             ),
         },
-        Extra: object,
-    }
+    },
+    extra=ALLOW_EXTRA,
 )
 
 

src/taskgraph/transforms/docker_image.py

@@ -5,6 +5,7 @@
 import logging
 import os
 import re
+from textwrap import dedent
 
 from voluptuous import Optional, Required
 
@@ -33,29 +34,78 @@
 #: Schema for docker_image transforms
 docker_image_schema = Schema(
     {
-        # Name of the docker image.
-        Required("name"): str,
-        # Name of the parent docker image.
-        Optional("parent"): str,
-        # Treeherder symbol.
-        Optional("symbol"): str,
-        # relative path (from config.path) to the file the docker image was defined
-        # in.
-        Optional("task-from"): str,
-        # Arguments to use for the Dockerfile.
-        Optional("args"): {str: str},
-        # Name of the docker image definition under taskcluster/docker, when
-        # different from the docker image name.
-        Optional("definition"): str,
-        # List of package tasks this docker image depends on.
-        Optional("packages"): [str],
+        Required(
+            "name",
+            description=dedent(
+                """
+                Name of the docker image.
+                """
+            ).lstrip(),
+        ): str,
+        Optional(
+            "parent",
+            description=dedent(
+                """
+                Name of the parent docker image.
+                """
+            ).lstrip(),
+        ): str,
+        Optional(
+            "symbol",
+            description=dedent(
+                """
+                Treeherder symbol.
+                """
+            ).lstrip(),
+        ): str,
+        Optional(
+            "task-from",
+            description=dedent(
+                """
+                Relative path (from config.path) to the file the docker image was defined in.
+                """
+            ).lstrip(),
+        ): str,
+        Optional(
+            "args",
+            description=dedent(
+                """
+                Arguments to use for the Dockerfile.
+                """
+            ).lstrip(),
+        ): {str: str},
+        Optional(
+            "definition",
+            description=dedent(
+                """
+                Name of the docker image definition under taskcluster/docker, when
+                different from the docker image name.
+                """
+            ).lstrip(),
+        ): str,
+        Optional(
+            "packages",
+            description=dedent(
+                """
+                List of package tasks this docker image depends on.
+                """
+            ).lstrip(),
+        ): [str],
         Optional(
             "index",
-            description="information for indexing this build so its artifacts can be discovered",
+            description=dedent(
+                """
+                Information for indexing this build so its artifacts can be discovered.
+                """
+            ).lstrip(),
         ): task_description_schema["index"],
         Optional(
             "cache",
-            description="Whether this image should be cached based on inputs.",
+            description=dedent(
+                """
+                Whether this image should be cached based on inputs.
+                """
+            ).lstrip(),
         ): bool,
     }
 )

src/taskgraph/transforms/fetch.py

@@ -9,6 +9,7 @@
 import os
 import re
 from dataclasses import dataclass
+from textwrap import dedent
 from typing import Callable
 
 from voluptuous import Extra, Optional, Required
@@ -26,25 +27,51 @@
 #: Schema for fetch transforms
 FETCH_SCHEMA = Schema(
     {
-        # Name of the task.
-        Required("name"): str,
-        # Relative path (from config.path) to the file the task was defined
-        # in.
-        Optional("task-from"): str,
-        # Description of the task.
-        Required("description"): str,
+        Required(
+            "name",
+            description=dedent(
+                """
+                Name of the task.
+                """.lstrip()
+            ),
+        ): str,
+        Optional(
+            "task-from",
+            description=dedent(
+                """
+                Relative path (from config.path) to the file the task was defined
+                in.
+                """.lstrip()
+            ),
+        ): str,
+        Required(
+            "description",
+            description=dedent(
+                """
+                Description of the task.
+                """.lstrip()
+            ),
+        ): str,
         Optional("expires-after"): str,
         Optional("docker-image"): object,
         Optional(
             "fetch-alias",
-            description="An alias that can be used instead of the real fetch task name in "
-            "fetch stanzas for tasks.",
+            description=dedent(
+                """
+                An alias that can be used instead of the real fetch task name in
+                fetch stanzas for tasks.
+                """.lstrip()
+            ),
         ): str,
         Optional(
             "artifact-prefix",
-            description="The prefix of the taskcluster artifact being uploaded. "
-            "Defaults to `public/`; if it starts with something other than "
-            "`public/` the artifact will require scopes to access.",
+            description=dedent(
+                """
+                The prefix of the taskcluster artifact being uploaded.
+                Defaults to `public/`; if it starts with something other than
+                `public/` the artifact will require scopes to access.
+                """.lstrip()
+            ),
         ): str,
         Optional("attributes"): {str: object},
         Required("fetch"): {

src/taskgraph/transforms/from_deps.py

@@ -14,7 +14,7 @@
 from copy import deepcopy
 from textwrap import dedent
 
-from voluptuous import Any, Extra, Optional, Required
+from voluptuous import ALLOW_EXTRA, Any, Optional, Required
 
 from taskgraph.transforms.base import TransformSequence
 from taskgraph.transforms.run import fetches_schema
@@ -109,8 +109,8 @@
                 ),
             ): {str: [fetches_schema]},
         },
-        Extra: object,
     },
+    extra=ALLOW_EXTRA,
 )
 
 transforms = TransformSequence()

src/taskgraph/transforms/matrix.py

@@ -10,7 +10,7 @@
 from copy import deepcopy
 from textwrap import dedent
 
-from voluptuous import Extra, Optional, Required
+from voluptuous import ALLOW_EXTRA, Extra, Optional, Required
 
 from taskgraph.transforms.base import TransformSequence
 from taskgraph.util.schema import Schema
@@ -58,8 +58,8 @@
             ): [str],
             Extra: [str],
         },
-        Extra: object,
     },
+    extra=ALLOW_EXTRA,
 )
 
 transforms = TransformSequence()

src/taskgraph/transforms/run/__init__.py

@@ -11,6 +11,7 @@
 
 import copy
 import logging
+from textwrap import dedent
 
 from voluptuous import Exclusive, Extra, Optional, Required
 
@@ -39,13 +40,28 @@
 #: Schema for a run transforms
 run_description_schema = Schema(
     {
-        # The name of the task and the task's label.  At least one must be specified,
-        # and the label will be generated from the name if necessary, by prepending
-        # the kind.
-        Optional("name"): str,
-        Optional("label"): str,
+        Optional(
+            "name",
+            description=dedent(
+                """
+                The name of the task. At least one of 'name' or 'label' must be
+                specified. If 'label' is not provided, it will be generated from
+                the 'name' by prepending the kind.
+                """
+            ),
+        ): str,
+        Optional(
+            "label",
+            description=dedent(
+                """
+                The label of the task. At least one of 'name' or 'label' must be
+                specified. If 'label' is not provided, it will be generated from
+                the 'name' by prepending the kind.
+                """
+            ),
+        ): str,
         # the following fields are passed directly through to the task description,
-        # possibly modified by the run implementation.  See
+        # possibly modified by the run implementation. See
         # taskcluster/taskgraph/transforms/task.py for the schema details.
         Required("description"): task_description_schema["description"],
         Optional("priority"): task_description_schema["priority"],
@@ -72,37 +88,80 @@
             "optimization"
         ],
         Optional("needs-sccache"): task_description_schema["needs-sccache"],
-        # The "when" section contains descriptions of the circumstances under which
-        # this task should be included in the task graph.  This will be converted
-        # into an optimization, so it cannot be specified in a run description that
-        # also gives 'optimization'.
-        Exclusive("when", "optimization"): {
-            # This task only needs to be run if a file matching one of the given
-            # patterns has changed in the push.  The patterns use the mozpack
-            # match function (python/mozbuild/mozpack/path.py).
-            Optional("files-changed"): [str],
+        Exclusive(
+            "when",
+            "optimization",
+            description=dedent(
+                """
+                The "when" section contains descriptions of the circumstances under
+                which this task should be included in the task graph. This will be
+                converted into an optimization, so it cannot be specified in a run
+                description that also gives 'optimization'.
+                """
+            ),
+        ): {
+            Optional(
+                "files-changed",
+                description=dedent(
+                    """
+                    This task only needs to be run if a file matching one of the given
+                    patterns has changed in the push. The patterns use the mozpack
+                    match function (python/mozbuild/mozpack/path.py).
+                    """
+                ),
+            ): [str],
         },
-        # A list of artifacts to install from 'fetch' tasks.
-        Optional("fetches"): {
+        Optional(
+            "fetches",
+            description=dedent(
+                """
+                A list of artifacts to install from 'fetch' tasks.
+                """
+            ),
+        ): {
             str: [
                 str,
                 fetches_schema,
             ],
         },
-        # A description of how to run this task.
-        "run": {
-            # The key to a run implementation in a peer module to this one
-            "using": str,
-            # Base work directory used to set up the task.
-            Optional("workdir"): str,
+        Required(
+            "run",
+            description=dedent(
+                """
+                A description of how to run this task.
+                """
+            ),
+        ): {
+            Required(
+                "using",
+                description=dedent(
+                    """
+                    The key to a run implementation in a peer module to this one.
+                    """
+                ),
+            ): str,
+            Optional(
+                "workdir",
+                description=dedent(
+                    """
+                    Base work directory used to set up the task.
+                    """
+                ),
+            ): str,
             # Any remaining content is verified against that run implementation's
             # own schema.
             Extra: object,
         },
         Required("worker-type"): task_description_schema["worker-type"],
-        # This object will be passed through to the task description, with additions
-        # provided by the task's run-using function
-        Optional("worker"): dict,
+        Required(
+            "worker",
+            description=dedent(
+                """
+                This object will be passed through to the task description, with additions
+                provided by the task's run-using function.
+                """
+            ),
+        ): dict,
     }
 )