docs: add doc comments to ensure all schemas are captured

The `#:` syntax is a special format that tells autodoc to include the
following object. This is better than using `:undoc-members:` which
would otherwise include every global variable in the modules.

Author: ahal

src/taskgraph/config.py

@@ -19,6 +19,8 @@
 
 logger = logging.getLogger(__name__)
 
+
+#: Schema for the graph config
 graph_config_schema = Schema(
     {
         # The trust-domain for this graph.
@@ -102,7 +104,6 @@
         Extra: object,
     }
 )
-"""Schema for GraphConfig"""
 
 
 @dataclass(frozen=True, eq=False)

src/taskgraph/decision.py

@@ -39,6 +39,7 @@
 }
 
 
+#: Schema for try_task_config.json version 2
 try_task_config_schema_v2 = Schema(
     {
         Optional("parameters"): {str: object},

src/taskgraph/parameters.py

@@ -28,7 +28,8 @@ class ParameterMismatch(Exception):
     """Raised when a parameters.yml has extra or missing parameters."""
 
 
-# Please keep this list sorted and in sync with docs/reference/parameters.rst
+#: Schema for base parameters.
+#: Please keep this list sorted and in sync with docs/reference/parameters.rst
 base_schema = Schema(
     {
         Required("base_repository"): str,

src/taskgraph/transforms/chunking.py

@@ -10,6 +10,7 @@
 from taskgraph.util.schema import Schema
 from taskgraph.util.templates import substitute
 
+#: Schema for chunking transforms
 CHUNK_SCHEMA = Schema(
     {
         # Optional, so it can be used for a subset of tasks in a kind

src/taskgraph/transforms/docker_image.py

@@ -30,6 +30,7 @@
 
 transforms = TransformSequence()
 
+#: Schema for docker_image transforms
 docker_image_schema = Schema(
     {
         # Name of the docker image.

src/taskgraph/transforms/fetch.py

@@ -23,6 +23,7 @@
 
 CACHE_TYPE = "content.v1"
 
+#: Schema for fetch transforms
 FETCH_SCHEMA = Schema(
     {
         # Name of the task.
@@ -53,7 +54,6 @@
     }
 )
 
-
 # define a collection of payload builders, depending on the worker implementation
 fetch_builders = {}
 

src/taskgraph/transforms/from_deps.py

@@ -23,6 +23,7 @@
 from taskgraph.util.schema import Schema, validate_schema
 from taskgraph.util.set_name import SET_NAME_MAP
 
+#: Schema for from_deps transforms
 FROM_DEPS_SCHEMA = Schema(
     {
         Required("from-deps"): {
@@ -111,7 +112,6 @@
         Extra: object,
     },
 )
-"""Schema for from_deps transforms."""
 
 transforms = TransformSequence()
 transforms.add_validate(FROM_DEPS_SCHEMA)

src/taskgraph/transforms/matrix.py

@@ -16,6 +16,7 @@
 from taskgraph.util.schema import Schema
 from taskgraph.util.templates import substitute_task_fields
 
+#: Schema for matrix transforms
 MATRIX_SCHEMA = Schema(
     {
         Required("name"): str,
@@ -60,7 +61,6 @@
         Extra: object,
     },
 )
-"""Schema for matrix transforms."""
 
 transforms = TransformSequence()
 transforms.add_validate(MATRIX_SCHEMA)

src/taskgraph/transforms/notify.py

@@ -54,6 +54,7 @@
 }
 """Map each type to its primary key that will be used in the route."""
 
+#: Schema for notify transforms
 NOTIFY_SCHEMA = Schema(
     {
         Exclusive("notify", "config"): {
@@ -90,7 +91,6 @@
     },
     extra=ALLOW_EXTRA,
 )
-"""Notify schema."""
 
 transforms = TransformSequence()
 transforms.add_validate(NOTIFY_SCHEMA)

src/taskgraph/transforms/run/__init__.py

@@ -36,7 +36,7 @@
     Optional("verify-hash"): bool,
 }
 
-# Schema for a build description
+#: 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,