Updated codeblocks and links part 2 for consistency, minor edits

Submitted by Mark Morton on Sept. 15, 2020, 7:01 p.m. | Patch ID: 176543

Details

Message ID 20200915190112.16269-1-mark.morton@windriver.com
State New
Headers show

Commit Message

Mark Morton Sept. 15, 2020, 7:01 p.m.
Signed-off-by: Mark Morton <mark.morton@windriver.com>
---
 .../test-manual/test-manual-intro.rst         | 31 +++++++++----------
 .../test-manual-understand-autobuilder.rst    | 18 +++++------
 2 files changed, 22 insertions(+), 27 deletions(-)

Patch hide | download patch | download mbox

diff --git a/documentation/test-manual/test-manual-intro.rst b/documentation/test-manual/test-manual-intro.rst
index d68ab73f4..62e23a297 100644
--- a/documentation/test-manual/test-manual-intro.rst
+++ b/documentation/test-manual/test-manual-intro.rst
@@ -27,14 +27,14 @@  loaded with information from the README files and notes from key
 engineers:
 
 -  *yocto-autobuilder2:* This
-   `README.md <http://git.yoctoproject.org/clean/cgit.cgi/yocto-autobuilder2/tree/README.md>`__
+   :yocto-git:`README.md </cgit.cgi/yocto-autobuilder2/tree/README.md>`
    is the main README which detials how to set up the Yocto Project
    Autobuilder. The ``yocto-autobuilder2`` repository represents the
    Yocto Project's console UI plugin to Buildbot and the configuration
    necessary to configure Buildbot to perform the testing the project
    requires.
 
--  *yocto-autobuilder-helper:* This `README <http://git.yoctoproject.org/clean/cgit.cgi/yocto-autobuilder-helper/tree/README/>`__
+-  *yocto-autobuilder-helper:* This :yocto-git:`README </cgit.cgi/yocto-autobuilder-helper/tree/README/>`
    and repository contains Yocto Project Autobuilder Helper scripts and
    configuration. The ``yocto-autobuilder-helper`` repository contains
    the "glue" logic that defines which tests to run and how to run them.
@@ -65,9 +65,9 @@  that the Yocto Project customizes using code from the
 resulting UI plug-in allows you to visualize builds in a way suited to
 the project's needs.
 
-A helper layer provides configuration and job management through
+A ``helper`` layer provides configuration and job management through
 scripts found in the ``yocto-autobuilder-helper`` repository. The
-helper layer contains the bulk of the build configuration
+``helper`` layer contains the bulk of the build configuration
 information and is release-specific, which makes it highly customizable
 on a per-project basis. The layer is CI system-agnostic and contains a
 number of Helper scripts that can generate build configurations from
@@ -137,10 +137,8 @@  thefollowing types of tests:
 
    $ bitbake image -c testimage 
    
-   The tests utilize the
-   :ref:`testimage* <ref-classes-testimage*>`
-   classes and the
-   :ref:`ref-tasks-testimage` task.
+   The tests utilize the :ref:`testimage* <ref-classes-testimage*>`
+   classes and the :ref:`ref-tasks-testimage` task.
 
 -  *Layer Testing:* The Autobuilder has the possibility to test whether
    specific layers work with the test of the system. The layers tested
@@ -155,9 +153,11 @@  thefollowing types of tests:
    ":yocto_wiki:`Ptest </wiki/Ptest>`" Wiki page for more
    information on Ptest.
 
--  *SDK Testing:* Image tests initiated through the following command: $
-   bitbake image -c testsdk The tests utilize the
-   :ref:`testsdk <ref-classes-testsdk>` class and
+-  *SDK Testing:* Image tests initiated through the following command:: 
+
+   $ bitbake image -c testsdk 
+   
+   The tests utilize the :ref:`testsdk <ref-classes-testsdk>` class and
    the ``do_testsdk`` task.
 
 -  *Unit Testing:* Unit tests on various components of the system run
@@ -253,12 +253,9 @@  Tests map into the codebase as follows:
    -  These tests build an image, boot it, and run tests against the
       image's content.
 
-   -  The code for these tests resides in
-      ``meta/lib/oeqa/runtime/cases/``.
+   -  The code for these tests resides in ``meta/lib/oeqa/runtime/cases/``.
 
-   -  You need to set the
-      :term:`IMAGE_CLASSES`
-      variable as follows::
+   -  You need to set the :term:`IMAGE_CLASSES` variable as follows::
       
       IMAGE_CLASSES += "testimage"
 
@@ -321,7 +318,7 @@  Test Examples
 =============
 
 This section provides example tests for each of the tests listed in the
-`How Tests Map to Areas of Code <#test-test-mapping>`__ section.
+:ref:`test-manual/test-manual-intro:How Tests Map to Areas of Code` section.
 
 For oeqa tests, testcases for each area reside in the main test
 directory at ``meta/lib/oeqa/selftest/cases`` directory.
diff --git a/documentation/test-manual/test-manual-understand-autobuilder.rst b/documentation/test-manual/test-manual-understand-autobuilder.rst
index 0d987d245..691e4de39 100644
--- a/documentation/test-manual/test-manual-understand-autobuilder.rst
+++ b/documentation/test-manual/test-manual-understand-autobuilder.rst
@@ -82,11 +82,11 @@  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``*
+1. *Run clobberdir*.
 
    This cleans out any previous build. Old builds are left around to
    allow easier debugging of failed builds. For additional information,
-   see :ref:`test-clobberdir`.
+   see :ref:`test-manual/test-manual-understand-autobuilder:clobberdir`.
 
 2. *Obtain yocto-autobuilder-helper*
 
@@ -110,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
-   :ref:`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
@@ -153,7 +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 :ref:`test-autobuilder-worker-janitor`.
+Worker Janitor runs this deletion. See :ref:`test-manual/test-manual-understand-autobuilder:Autobuilder Worker Janitor`.
 
 .. _test-autobuilder-clone-cache:
 
@@ -165,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 :ref:`Autobuilder Worker
-Janitor`.
+Worker Janitor. See :ref:`test-manual/test-manual-understand-autobuilder:Autobuilder Worker Janitor`.
 
 .. _test-autobuilder-worker-janitor:
 
@@ -174,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 :ref:`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.
 
@@ -196,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:
@@ -263,7 +261,7 @@  of post-build steps, including:
    generated to the remote server.
 
 4. Cleanup the build directory using
-   :ref:`test-clobberdir` if the build was successful,
+   :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:

Comments

Nicolas Dechesne Sept. 16, 2020, 1:57 p.m.
hi Mark,

On Tue, Sep 15, 2020 at 9:06 PM Mark Morton <Mark.Morton@windriver.com> wrote:
>
> Signed-off-by: Mark Morton <mark.morton@windriver.com>

thanks! I just pushed the test-manual updates in the sphinx branch. I
squashed both of your commit, and I added a few additional fixup of
mine as well (also squashed them). There was something weird with many
URL link, you had many links like this:

`https://docs.python.org/3/library/unittest.html <#>`__

I think they should simply be:

https://docs.python.org/3/library/unittest.html

http links are managed automatically.

there were a couple of indentation issues (when nesting literal blocks
in lists), and I fixed them.

If you are curious, here is the patch I had on top of your 2 patches,
before I squashed them all.

https://git.linaro.org/people/nicolas.dechesne/yocto-docs.git/commit/?h=review&id=718b075634ad827682a3389359b66cf0c0de41b7

If you notice anything wrong, please send a patch on top of 'sphinx' branch.

> ---
>  .../test-manual/test-manual-intro.rst         | 31 +++++++++----------
>  .../test-manual-understand-autobuilder.rst    | 18 +++++------
>  2 files changed, 22 insertions(+), 27 deletions(-)
>
> diff --git a/documentation/test-manual/test-manual-intro.rst b/documentation/test-manual/test-manual-intro.rst
> index d68ab73f4..62e23a297 100644
> --- a/documentation/test-manual/test-manual-intro.rst
> +++ b/documentation/test-manual/test-manual-intro.rst
> @@ -27,14 +27,14 @@ loaded with information from the README files and notes from key
>  engineers:
>
>  -  *yocto-autobuilder2:* This
> -   `README.md <http://git.yoctoproject.org/clean/cgit.cgi/yocto-autobuilder2/tree/README.md>`__
> +   :yocto-git:`README.md </cgit.cgi/yocto-autobuilder2/tree/README.md>`
>     is the main README which detials how to set up the Yocto Project
>     Autobuilder. The ``yocto-autobuilder2`` repository represents the
>     Yocto Project's console UI plugin to Buildbot and the configuration
>     necessary to configure Buildbot to perform the testing the project
>     requires.
>
> --  *yocto-autobuilder-helper:* This `README <http://git.yoctoproject.org/clean/cgit.cgi/yocto-autobuilder-helper/tree/README/>`__
> +-  *yocto-autobuilder-helper:* This :yocto-git:`README </cgit.cgi/yocto-autobuilder-helper/tree/README/>`
>     and repository contains Yocto Project Autobuilder Helper scripts and
>     configuration. The ``yocto-autobuilder-helper`` repository contains
>     the "glue" logic that defines which tests to run and how to run them.
> @@ -65,9 +65,9 @@ that the Yocto Project customizes using code from the
>  resulting UI plug-in allows you to visualize builds in a way suited to
>  the project's needs.
>
> -A helper layer provides configuration and job management through
> +A ``helper`` layer provides configuration and job management through
>  scripts found in the ``yocto-autobuilder-helper`` repository. The
> -helper layer contains the bulk of the build configuration
> +``helper`` layer contains the bulk of the build configuration
>  information and is release-specific, which makes it highly customizable
>  on a per-project basis. The layer is CI system-agnostic and contains a
>  number of Helper scripts that can generate build configurations from
> @@ -137,10 +137,8 @@ thefollowing types of tests:
>
>     $ bitbake image -c testimage
>
> -   The tests utilize the
> -   :ref:`testimage* <ref-classes-testimage*>`
> -   classes and the
> -   :ref:`ref-tasks-testimage` task.
> +   The tests utilize the :ref:`testimage* <ref-classes-testimage*>`
> +   classes and the :ref:`ref-tasks-testimage` task.
>
>  -  *Layer Testing:* The Autobuilder has the possibility to test whether
>     specific layers work with the test of the system. The layers tested
> @@ -155,9 +153,11 @@ thefollowing types of tests:
>     ":yocto_wiki:`Ptest </wiki/Ptest>`" Wiki page for more
>     information on Ptest.
>
> --  *SDK Testing:* Image tests initiated through the following command: $
> -   bitbake image -c testsdk The tests utilize the
> -   :ref:`testsdk <ref-classes-testsdk>` class and
> +-  *SDK Testing:* Image tests initiated through the following command::
> +
> +   $ bitbake image -c testsdk
> +
> +   The tests utilize the :ref:`testsdk <ref-classes-testsdk>` class and
>     the ``do_testsdk`` task.
>
>  -  *Unit Testing:* Unit tests on various components of the system run
> @@ -253,12 +253,9 @@ Tests map into the codebase as follows:
>     -  These tests build an image, boot it, and run tests against the
>        image's content.
>
> -   -  The code for these tests resides in
> -      ``meta/lib/oeqa/runtime/cases/``.
> +   -  The code for these tests resides in ``meta/lib/oeqa/runtime/cases/``.
>
> -   -  You need to set the
> -      :term:`IMAGE_CLASSES`
> -      variable as follows::
> +   -  You need to set the :term:`IMAGE_CLASSES` variable as follows::
>
>        IMAGE_CLASSES += "testimage"
>
> @@ -321,7 +318,7 @@ Test Examples
>  =============
>
>  This section provides example tests for each of the tests listed in the
> -`How Tests Map to Areas of Code <#test-test-mapping>`__ section.
> +:ref:`test-manual/test-manual-intro:How Tests Map to Areas of Code` section.
>
>  For oeqa tests, testcases for each area reside in the main test
>  directory at ``meta/lib/oeqa/selftest/cases`` directory.
> diff --git a/documentation/test-manual/test-manual-understand-autobuilder.rst b/documentation/test-manual/test-manual-understand-autobuilder.rst
> index 0d987d245..691e4de39 100644
> --- a/documentation/test-manual/test-manual-understand-autobuilder.rst
> +++ b/documentation/test-manual/test-manual-understand-autobuilder.rst
> @@ -82,11 +82,11 @@ 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``*
> +1. *Run clobberdir*.
>
>     This cleans out any previous build. Old builds are left around to
>     allow easier debugging of failed builds. For additional information,
> -   see :ref:`test-clobberdir`.
> +   see :ref:`test-manual/test-manual-understand-autobuilder:clobberdir`.
>
>  2. *Obtain yocto-autobuilder-helper*
>
> @@ -110,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
> -   :ref:`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
> @@ -153,7 +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 :ref:`test-autobuilder-worker-janitor`.
> +Worker Janitor runs this deletion. See :ref:`test-manual/test-manual-understand-autobuilder:Autobuilder Worker Janitor`.
>
>  .. _test-autobuilder-clone-cache:
>
> @@ -165,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 :ref:`Autobuilder Worker
> -Janitor`.
> +Worker Janitor. See :ref:`test-manual/test-manual-understand-autobuilder:Autobuilder Worker Janitor`.
>
>  .. _test-autobuilder-worker-janitor:
>
> @@ -174,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 :ref:`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.
>
> @@ -196,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:
> @@ -263,7 +261,7 @@ of post-build steps, including:
>     generated to the remote server.
>
>  4. Cleanup the build directory using
> -   :ref:`test-clobberdir` if the build was successful,
> +   :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:
> --
> 2.17.1
>
>
> 
>
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.

View/Reply Online (#364): https://lists.yoctoproject.org/g/docs/message/364
Mute This Topic: https://lists.yoctoproject.org/mt/76872300/3617530
Group Owner: docs+owner@lists.yoctoproject.org
Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub  [oe-patchwork@oe-patch.openembedded.org]
-=-=-=-=-=-=-=-=-=-=-=-