Bug 1471767 - taskcluster documentation fixes, r=dustin

Assorted fixes from trawling the sphinx logs - malformed formatting, broken references, leftovers from renaming action-task to action-callback and removing
yaml-templates, docstring fixes to make sphinx happier, and typos.

MozReview-Commit-ID: 6jUOljdLoE2

--HG--
extra : rebase_source : f2a9dbcde5180f760a80f47691a70eba76e58bad

taskcluster/docs/caches.rst

@@ -87,7 +87,7 @@ Workspace Caches
 Other
 :::::
 
-``level-{{level}}-tooltool-cache-{{hash}}
+``level-{{level}}-tooltool-cache-{{hash}}``
    Tooltool invocations should use this cache. Tooltool will store files here
    indexed by their hash.
 

taskcluster/docs/docker-images.rst

@@ -27,13 +27,13 @@ pushed to vcs.
 Task Images (build-on-push)
 :::::::::::::::::::::::::::
 
-Images can be uploaded as a task artifact, [indexed](#task-image-index-namespace) under
+Images can be uploaded as a task artifact, :ref:`indexed <task-image-index-namespace>` under
 a given namespace, and used in other tasks by referencing the task ID.
 
 Important to note, these images do not require building and pushing to a docker registry, and are
 built per push (if necessary) and uploaded as task artifacts.
 
-The decision task that is run per push will [determine](#context-directory-hashing)
+The decision task that is run per push will :ref:`determine <context-directory-hashing>`
 if the image needs to be built based on the hash of the context directory and if the image
 exists under the namespace for a given branch.
 
@@ -45,12 +45,14 @@ pushes to any branch will use that already built image.
 
 To use within an in-tree task definition, the format is:
 
-```yaml
-image:
-  type: 'task-image'
-  path: 'public/image.tar.zst'
-  taskId: '{{#task_id_for_image}}builder{{/task_id_for_image}}'
-```
+.. code-block:: yaml
+
+    image:
+        type: 'task-image'
+        path: 'public/image.tar.zst'
+        taskId: '<task_id_for_image_builder>'
+
+.. _context-directory-hashing:
 
 Context Directory Hashing
 .........................
@@ -63,15 +65,18 @@ Note: this is the contents of *only* the context directory, not the
 image contents.
 
 The decision task will:
+
 1. Recursively collect the paths of all files within the context directory
 2. Sort the filenames alphabetically to ensure the hash is consistently calculated
-3. Generate a sha256 hash of the contents of each file.
-4. All file hashes will then be combined with their path and used to update the hash
-of the context directory.
+3. Generate a sha256 hash of the contents of each file
+4. All file hashes will then be combined with their path and used to update the
+   hash of the context directory
 
 This ensures that the hash is consistently calculated and path changes will result
 in different hashes being generated.
 
+.. _task-image-index-namespace:
+
 Task Image Index Namespace
 ..........................
 
@@ -105,7 +110,7 @@ Example:
 Each image has a repo digest, an image hash, and a version. The repo digest is
 stored in the ``HASH`` file in the image directory  and used to refer to the
 image as above.  The version is in ``VERSION``.  The image hash is used in
-`chain-of-trust verification <http://scriptworker.readthedocs.io/en/latest/chain_of_trust.html>`
+`chain-of-trust verification <https://scriptworker.readthedocs.io/en/latest/chain_of_trust.html>`_
 in `scriptworker <https://github.com/mozilla-releng/scriptworker>`_.
 
 The version file only serves to provide convenient names, such that old
@@ -168,7 +173,7 @@ task definitions.
 
 The change is now safe to use in Try pushes.  However, if the image is used in
 building releases then it is *not* safe to land to an integration branch until
-the whitelists in `scriptworker
+the whitelists in `scriptworker's constants.py
 <https://github.com/mozilla-releng/scriptworker/blob/master/scriptworker/constants.py>`_
 have also been updated. These whitelists use the image hash, not the repo
 digest.

taskcluster/docs/how-tos.rst

@@ -57,7 +57,7 @@ If you are working on an action task and wish to test it out locally, use the
 
    .. code-block:: none
 
-        ./mach taskgraph test-action-task \
+        ./mach taskgraph test-action-callback \
             --task-id I4gu9KDmSZWu3KHx6ba6tw --task-group-id sMO4ybV9Qb2tmcI1sDHClQ \
             --input input.yml hello_world_action
 

taskcluster/docs/kinds.rst

@@ -159,11 +159,7 @@ The tasks to generate each docker image have predictable labels:
 Docker images are built from subdirectories of ``taskcluster/docker``, using
 ``docker build``.  There is currently no capability for one Docker image to
 depend on another in-tree docker image, without uploading the latter to a
-Docker repository
-
-The task definition used to create the image-building tasks is given in
-``image.yml`` in the kind directory, and is interpreted as a :doc:`YAML
-Template <yaml-templates>`.
+Docker repository.
 
 balrog
 ------

taskcluster/docs/loading.rst

@@ -16,7 +16,7 @@ The ``path`` is the path to the configuration directory for the kind. This
 can be used to load extra data, templates, etc.
 
 The ``parameters`` give details on which to base the task generation. See
-:ref:`parameters` for details.
+:doc:`parameters` for details.
 
 At the time this method is called, all kinds on which this kind depends
 (that is, specified in the ``kind-dependencies`` key in ``config``)

taskcluster/docs/mach.rst

@@ -22,7 +22,7 @@ graph-generation process and output the results.
    Get the optimized task graph
 
 ``mach taskgraph morphed``
-   Get the morhped task graph
+   Get the morphed task graph
 
 See :doc:`how-tos` for further practical tips on debugging task-graph mechanics
 locally.

taskcluster/docs/optimization-schedules.rst

@@ -62,7 +62,6 @@ File Annotation
 
 Files are annotated with their affected components in ``moz.build`` files with stanzas like ::
 
-    
     with Files('**/*.py'):
         SCHEDULES.inclusive += ['py-lint']
 
@@ -78,7 +77,8 @@ For cases where an inclusive component is affected exclusively (such as the pyth
     with Files('**/pep8rc'):
         SCHEDULES.exclusive = ['py-lint']
 
-If multiple stanzas set ``SCHEDULES.exclusive``, the last one will take precedence.  Thus the following will set ``SCHEDULES.exclusive`` to ``hpux`` for all files except those under ``docs/``.
+If multiple stanzas set ``SCHEDULES.exclusive``, the last one will take precedence.  Thus the following
+will set ``SCHEDULES.exclusive`` to ``hpux`` for all files except those under ``docs/``. ::
 
     with Files('**'):
         SCHEDULES.exclusive = ['hpux']

taskcluster/docs/taskcluster-config.rst

@@ -32,4 +32,4 @@ You can test your patches with something like this, assuming ``.`` is a checkout
   ci-admin diff --ci-configuration-directory .
 
 .. _ci-configuration: https://hg.mozilla.org/build/ci-configuration/file
-.. _ci-configuration: https://hg.mozilla.org/build/ci-admin/file
+.. _ci-admin: https://hg.mozilla.org/build/ci-admin/file

taskcluster/docs/taskgraph.rst

@@ -97,7 +97,7 @@ Graph generation, as run via ``mach taskgraph decision``, proceeds as follows:
    The result is the "target task graph".
 #. Optimize the target task graph using task-specific optimization methods.
    The result is the "optimized task graph" with fewer nodes than the target
-   task graph.  See :ref:`optimization`.
+   task graph.  See :doc:`optimization`.
 #. Morph the graph. Morphs are like syntactic sugar: they keep the same meaning,
    but express it in a lower-level way. These generally work around limitations
    in the TaskCluster platform, such as number of dependencies or routes in
@@ -137,7 +137,7 @@ Action Tasks are tasks which help you to schedule new jobs via Treeherder's
 task ID of the push and a comma separated list of task labels which need to be
 scheduled.
 
-This task invokes ``mach taskgraph action-task`` which builds up a task graph of
+This task invokes ``mach taskgraph action-callback`` which builds up a task graph of
 the requested tasks. This graph is optimized using the tasks running initially in
 the same push, due to the decision task.
 
@@ -183,7 +183,7 @@ Graph Configuration
 
 There are several configuration settings that are pertain to the entire
 taskgraph. These are specified in :file:`config.yml` at the root of the
-taskgraph configuration (typically :file:`taskcluster/ci`). The available
+taskgraph configuration (typically :file:`taskcluster/ci/`). The available
 settings are documented inline in `taskcluster/taskgraph/config.py
 <https://dxr.mozilla.org/mozilla-central/source/taskcluster/taskgraph/config.py>`_.
 
@@ -194,7 +194,7 @@ Trust Domain
 
 When publishing and signing releases, that tasks verify their definition and
 all upstream tasks come from a decision task based on a trusted tree. (see
-`chain-of-trust verification <http://scriptworker.readthedocs.io/en/latest/chain_of_trust.html>`_).
+`chain-of-trust verification <https://scriptworker.readthedocs.io/en/latest/chain_of_trust.html>`_).
 Firefox and Thunderbird share the taskgraph code and in particular, they have
 separate taskgraph configurations and in particular distinct decision tasks.
 Although they use identical docker images and toolchains, in order to track the

taskcluster/docs/transforms.rst

@@ -23,7 +23,7 @@ Transform Functions
 
 Each transformation looks like this:
 
-.. code-block::
+.. code-block:: python
 
     @transforms.add
     def transform_an_item(config, items):

taskcluster/taskgraph/transforms/job/__init__.py

@@ -183,8 +183,8 @@ def run_job_using(worker_implementation, run_using, schema=None, defaults={}):
     jobs with the given worker implementation and `run.using` property.  If
     `schema` is given, the job's run field will be verified to match it.
 
-    The decorated function should have the signature `using_foo(config, job,
-    taskdesc) and should modify the task description in-place.  The skeleton of
+    The decorated function should have the signature `using_foo(config, job, taskdesc)`
+    and should modify the task description in-place.  The skeleton of
     the task description is already set up, but without a payload."""
     def wrap(func):
         for_run_using = registry.setdefault(run_using, {})

taskcluster/taskgraph/transforms/upload_generated_sources.py

@@ -3,8 +3,7 @@
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 """
 Transform the upload-generated-files task description template,
-  taskcluster/ci/upload-generated-sources/kind.yml
-into an actual task description.
+taskcluster/ci/upload-generated-sources/kind.yml, into an actual task description.
 """
 
 from __future__ import absolute_import, print_function, unicode_literals

taskcluster/taskgraph/transforms/upload_symbols.py

@@ -3,8 +3,7 @@
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 """
 Transform the upload-symbols task description template,
-  taskcluster/ci/upload-symbols/job-template.yml
-into an actual task description.
+taskcluster/ci/upload-symbols/job-template.yml into an actual task description.
 """
 
 from __future__ import absolute_import, print_function, unicode_literals

taskcluster/taskgraph/util/schema.py

@@ -75,7 +75,7 @@ def resolve_keyed_by(item, field, item_name, **extra_values):
                     win.*: 6
                     default: 12
 
-    a call to `resolve_keyed_by(item, 'job.chunks', item['thing-name'])
+    a call to `resolve_keyed_by(item, 'job.chunks', item['thing-name'])`
     would mutate item in-place to::
 
         job: