1 files changed, 78 insertions, 62 deletions

diff --git a/documentation/test-manual/test-manual-understand-autobuilder.rst b/documentation/test-manual/test-manual-understand-autobuilder.rst
index 8d3c844156..0809190b5b 100644
--- a/documentation/test-manual/test-manual-understand-autobuilder.rst
+++ b/documentation/test-manual/test-manual-understand-autobuilder.rst
@@ -10,7 +10,7 @@ Execution Flow within the Autobuilder
 The “a-full” and “a-quick” targets are the usual entry points into the
 Autobuilder and it makes sense to follow the process through the system
 starting there. This is best visualised from the Autobuilder Console
-view (`https://autobuilder.yoctoproject.org/typhoon/#/console <#>`__).
+view (:yocto_ab:`/typhoon/#/console`).
 
 Each item along the top of that view represents some “target build” and
 these targets are all run in parallel. The ‘full’ build will trigger the
@@ -20,32 +20,48 @@ each of those targets on a seperate buildbot worker. To understand the
 configuration, you need to look at the entry on ``config.json`` file
 within the ``yocto-autobuilder-helper`` repository. The targets are
 defined in the ‘overrides’ section, a quick example could be qemux86-64
-which looks like:"qemux86-64" : { "MACHINE" : "qemux86-64", "TEMPLATE" :
-"arch-qemu", "step1" : { "extravars" : [ "IMAGE_FSTYPES_append = ' wic
-wic.bmap'" ] } },And to expand that, you need the “arch-qemu” entry from
-the “templates” section, which looks like:"arch-qemu" : { "BUILDINFO" :
-true, "BUILDHISTORY" : true, "step1" : { "BBTARGETS" : "core-image-sato
-core-image-sato-dev core-image-sato-sdk core-image-minimal
-core-image-minimal-dev core-image-sato:do_populate_sdk", "SANITYTARGETS"
-: "core-image-minimal:do_testimage core-image-sato:do_testimage
-core-image-sato-sdk:do_testimage core-image-sato:do_testsdk" }, "step2"
-: { "SDKMACHINE" : "x86_64", "BBTARGETS" :
-"core-image-sato:do_populate_sdk core-image-minimal:do_populate_sdk_ext
-core-image-sato:do_populate_sdk_ext", "SANITYTARGETS" :
-"core-image-sato:do_testsdk core-image-minimal:do_testsdkext
-core-image-sato:do_testsdkext" }, "step3" : { "BUILDHISTORY" : false,
-"EXTRACMDS" : ["${SCRIPTSDIR}/checkvnc; DISPLAY=:1 oe-selftest
-${HELPERSTMACHTARGS} -j 15"], "ADDLAYER" :
-["${BUILDDIR}/../meta-selftest"] } },Combining these two entries you can
-see that “qemux86-64” is a three step build where the
-``bitbake BBTARGETS`` would be run, then ``bitbake
-                SANITYTARGETS`` for each step; all for
+which looks like::
+
+   "qemux86-64" : {
+         "MACHINE" : "qemux86-64",
+         "TEMPLATE" : "arch-qemu",
+         "step1" : {
+               "extravars" : [
+                     "IMAGE_FSTYPES_append = ' wic wic.bmap'"
+                    ]
+        }
+   },
+
+And to expand that, you need the “arch-qemu” entry from
+the “templates” section, which looks like::
+
+   "arch-qemu" : {
+         "BUILDINFO" : true,
+         "BUILDHISTORY" : true,
+         "step1" : {
+               "BBTARGETS" : "core-image-sato core-image-sato-dev core-image-sato-sdk core-image-minimal core-image-minimal-dev core-image-sato:do_populate_sdk",
+         "SANITYTARGETS" : "core-image-minimal:do_testimage core-image-sato:do_testimage core-image-sato-sdk:do_testimage core-image-sato:do_testsdk"
+         },
+         "step2" : {
+               "SDKMACHINE" : "x86_64",
+               "BBTARGETS" : "core-image-sato:do_populate_sdk core-image-minimal:do_populate_sdk_ext core-image-sato:do_populate_sdk_ext",
+               "SANITYTARGETS" : "core-image-sato:do_testsdk core-image-minimal:do_testsdkext core-image-sato:do_testsdkext"
+         },
+         "step3" : {
+               "BUILDHISTORY" : false,
+               "EXTRACMDS" : ["${SCRIPTSDIR}/checkvnc; DISPLAY=:1 oe-selftest ${HELPERSTMACHTARGS} -j 15"],
+               "ADDLAYER" : ["${BUILDDIR}/../meta-selftest"]
+         }
+   },
+
+Combining these two entries you can see that “qemux86-64” is a three step build where the
+``bitbake BBTARGETS`` would be run, then ``bitbake SANITYTARGETS`` for each step; all for
 ``MACHINE=”qemx86-64”`` but with differing SDKMACHINE settings. In step
 1 an extra variable is added to the ``auto.conf`` file to enable wic
 image generation.
 
 While not every detail of this is covered here, you can see how the
-templating mechanism allows quite complex configurations to be built up
+template mechanism allows quite complex configurations to be built up
 yet allows duplication and repetition to be kept to a minimum.
 
 The different build targets are designed to allow for parallelisation,
@@ -66,13 +82,13 @@ For each given target in a build, the Autobuilder executes several
 steps. These are configured in ``yocto-autobuilder2/builders.py`` and
 roughly consist of:
 
-1. *Run ``clobberdir``*
+#. *Run clobberdir*.
 
    This cleans out any previous build. Old builds are left around to
    allow easier debugging of failed builds. For additional information,
-   see ```clobberdir`` <#test-clobberdir>`__.
+   see :ref:`test-manual/test-manual-understand-autobuilder:clobberdir`.
 
-2. *Obtain yocto-autobuilder-helper*
+#. *Obtain yocto-autobuilder-helper*
 
    This step clones the ``yocto-autobuilder-helper`` git repository.
    This is necessary to prevent the requirement to maintain all the
@@ -80,12 +96,12 @@ roughly consist of:
    matches the release being built so we can support older releases and
    still make changes in newer ones.
 
-3. *Write layerinfo.json*
+#. *Write layerinfo.json*
 
    This transfers data in the Buildbot UI when the build was configured
    to the Helper.
 
-4. *Call scripts/shared-repo-unpack*
+#. *Call scripts/shared-repo-unpack*
 
    This is a call into the Helper scripts to set up a checkout of all
    the pieces this build might need. It might clone the BitBake
@@ -94,7 +110,7 @@ roughly consist of:
    from the ``layerinfo.json`` file to help understand the
    configuration. It will also use a local cache of repositories to
    speed up the clone checkouts. For additional information, see
-   `Autobuilder Clone Cache <#test-autobuilder-clone-cache>`__.
+   :ref:`test-manual/test-manual-understand-autobuilder:Autobuilder Clone Cache`.
 
    This step has two possible modes of operation. If the build is part
    of a parent build, its possible that all the repositories needed may
@@ -114,7 +130,7 @@ roughly consist of:
    available, it would clone from the cache and the upstreams as
    necessary. This is considered the fallback mode.
 
-5. *Call scripts/run-config*
+#. *Call scripts/run-config*
 
    This is another call into the Helper scripts where its expected that
    the main functionality of this target will be executed.
@@ -137,8 +153,7 @@ special script that moves files to a special location, rather than
 deleting them. Files in this location are deleted by an ``rm`` command,
 which is run under ``ionice -c 3``. For example, the deletion only
 happens when there is idle IO capacity on the Worker. The Autobuilder
-Worker Janitor runs this deletion. See `Autobuilder Worker
-Janitor <#test-autobuilder-worker-janitor>`__.
+Worker Janitor runs this deletion. See :ref:`test-manual/test-manual-understand-autobuilder:Autobuilder Worker Janitor`.
 
 .. _test-autobuilder-clone-cache:
 
@@ -150,8 +165,7 @@ on the Autobuilder. We therefore have a stash of commonly used
 repositories pre-cloned on the Workers. Data is fetched from these
 during clones first, then "topped up" with later revisions from any
 upstream when necesary. The cache is maintained by the Autobuilder
-Worker Janitor. See `Autobuilder Worker
-Janitor <#test-autobuilder-worker-janitor>`__.
+Worker Janitor. See :ref:`test-manual/test-manual-understand-autobuilder:Autobuilder Worker Janitor`.
 
 .. _test-autobuilder-worker-janitor:
 
@@ -159,8 +173,7 @@ Autobuilder Worker Janitor
 --------------------------
 
 This is a process running on each Worker that performs two basic
-operations, including background file deletion at IO idle (see `Target
-Execution: clobberdir <#test-list-tgt-exec-clobberdir>`__) and
+operations, including background file deletion at IO idle (see :ref:`test-manual/test-manual-understand-autobuilder:Autobuilder Target Execution Overview`: Run clobberdir) and
 maintainenance of a cache of cloned repositories to improve the speed
 the system can checkout repositories.
 
@@ -181,7 +194,7 @@ Shared SSTATE_DIR
 
 The Workers are all connected over NFS which allows the ``sstate``
 directory to be shared between them. This means once a Worker has built
-an artefact, all the others can benefit from it. Usage of the directory
+an artifact, all the others can benefit from it. Usage of the directory
 within the directory is designed for sharing over NFS.
 
 .. _test-resulttool:
@@ -198,7 +211,7 @@ Resulttool is part of OpenEmbedded-Core and is used to manipulate these
 json results files. It has the ability to merge files together, display
 reports of the test results and compare different result files.
 
-For details, see `https://wiki.yoctoproject.org/wiki/Resulttool <#>`__.
+For details, see :yocto_wiki:`/wiki/Resulttool`.
 
 .. _test-run-config-tgt-execution:
 
@@ -209,50 +222,46 @@ The ``scripts/run-config`` execution is where most of the work within
 the Autobuilder happens. It runs through a number of steps; the first
 are general setup steps that are run once and include:
 
-1. Set up any ``buildtools-tarball`` if configured.
+#. Set up any ``buildtools-tarball`` if configured.
 
-2. Call "buildhistory-init" if buildhistory is configured.
+#. Call "buildhistory-init" if buildhistory is configured.
 
 For each step that is configured in ``config.json``, it will perform the
 following:
 
-## WRITER's question: What does "logging in as stepXa" and others refer
-to below? ##
-
-1. Add any layers that are specified using the
+#. Add any layers that are specified using the
    ``bitbake-layers add-layer`` command (logging as stepXa)
 
-2. Call the ``scripts/setup-config`` script to generate the necessary
+#. Call the ``scripts/setup-config`` script to generate the necessary
    ``auto.conf`` configuration file for the build
 
-3. Run the ``bitbake BBTARGETS`` command (logging as stepXb)
+#. Run the ``bitbake BBTARGETS`` command (logging as stepXb)
 
-4. Run the ``bitbake SANITYTARGETS`` command (logging as stepXc)
+#. Run the ``bitbake SANITYTARGETS`` command (logging as stepXc)
 
-5. Run the ``EXTRACMDS`` command, which are run within the BitBake build
+#. Run the ``EXTRACMDS`` command, which are run within the BitBake build
    environment (logging as stepXd)
 
-6. Run the ``EXTRAPLAINCMDS`` command(s), which are run outside the
+#. Run the ``EXTRAPLAINCMDS`` command(s), which are run outside the
    BitBake build environment (logging as stepXd)
 
-7. Remove any layers added in `step
-   1 <#test-run-config-add-layers-step>`__ using the
-   ``bitbake-layers remove-layer`` command (logging as stepXa)
+#. Remove any layers added in step
+   1 using the ``bitbake-layers remove-layer`` command (logging as stepXa)
 
 Once the execution steps above complete, ``run-config`` executes a set
 of post-build steps, including:
 
-1. Call ``scripts/publish-artifacts`` to collect any output which is to
+#. Call ``scripts/publish-artifacts`` to collect any output which is to
    be saved from the build.
 
-2. Call ``scripts/collect-results`` to collect any test results to be
+#. Call ``scripts/collect-results`` to collect any test results to be
    saved from the build.
 
-3. Call ``scripts/upload-error-reports`` to send any error reports
+#. Call ``scripts/upload-error-reports`` to send any error reports
    generated to the remote server.
 
-4. Cleanup the build directory using
-   ```clobberdir`` <#test-clobberdir>`__ if the build was successful,
+#. Cleanup the build directory using
+   :ref:`test-manual/test-manual-understand-autobuilder:clobberdir` if the build was successful,
    else rename it to “build-renamed” for potential future debugging.
 
 .. _test-deploying-yp-autobuilder:
@@ -279,11 +288,18 @@ The standard ``config.json`` minimally attempts to allow substitution of
 the paths. The Helper script repository includes a
 ``local-example.json`` file to show how you could override these from a
 separate configuration file. Pass the following into the environment of
-the Autobuilder:$ ABHELPER_JSON="config.json local-example.json"As
-another example, you could also pass the following into the
-environment:$ ABHELPER_JSON="config.json /some/location/local.json"One
-issue users often run into is validation of the ``config.json`` files. A
+the Autobuilder::
+
+   $ ABHELPER_JSON="config.json local-example.json"
+
+As another example, you could also pass the following into the
+environment::
+
+   $ ABHELPER_JSON="config.json /some/location/local.json"
+
+One issue users often run into is validation of the ``config.json`` files. A
 tip for minimizing issues from invalid json files is to use a Git
 ``pre-commit-hook.sh`` script to verify the JSON file before committing
-it. Create a symbolic link as follows:$ ln -s
-../../scripts/pre-commit-hook.sh .git/hooks/pre-commit
+it. Create a symbolic link as follows::
+
+   $ ln -s ../../scripts/pre-commit-hook.sh .git/hooks/pre-commit