Add link anchors to documentation and fix broken link to removed Plai…

…nbox docs (#543) * Add anchors to each fields for every Checkbox units The fields are described as definition lists in HTML. This is, by default, rendered without any id anchor in HTML. Manually adding a reference in ReStructuredText allows to point a user to the field by using the HTML id anchor. For instance: /reference/units/test-plan/#test-plan-bootstrap-include-field will point to the bootstrap_include field of the test plan unit. These can also be used in rst directly by using :ref:. See [1] for more info. [1] https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html#add-links * Remove unused references inside flags section Since there is now a reference to the `flags` section, these sub-references may not be useful. * Fix link to category-overrides reference The plainbox documentation website has been decomissioned, so the external link does not work anymore. Point to an internal reference instead. * Remove unnecessary table of contents * Add refs for the different flags in the job unit
canonical · Jun 13, 2023 · ae2b98c · ae2b98c
1 parent e309302
commit ae2b98c
Show file tree

Hide file tree

Showing 9 changed files with 123 additions and 18 deletions.
diff --git a/docs/explanation/understanding.rst b/docs/explanation/understanding.rst
@@ -1,8 +1,6 @@
 Understanding Checkbox
 ======================
 
-.. contents::
-
 Checkbox by itself doesn't test anything. It uses unit definitions grouped in
 providers to actually run or do something.
 

diff --git a/docs/how-to/nested-test-plan.rst b/docs/how-to/nested-test-plan.rst
@@ -19,7 +19,7 @@ test plan sections in sync and up-to-date.
 What if it could be possible now to have nested test plans. One being built by
 aggregating sections from one or more "base test plans"?
 
-Let's review in detail this new feature available in checkbox since plainbox 0.29
+Let's review this feature in detail.
 
 Quick start
 ===========
@@ -196,8 +196,7 @@ The jobs execution order is:
 How to change category or certification status of jobs coming from nested parts?
 --------------------------------------------------------------------------------
 
-The `test plan override mechanism
-<http://plainbox.readthedocs.io/en/latest/manpages/plainbox-test-plan-units.html?highlight=category-overrides>`_
+The :ref:`test plan override mechanism<Test Plan category-overrides field>`
 still works with nested parts. For example the ``hello`` job from the Baz
 provider was defined as a blocker and did not have a category.
 

diff --git a/docs/reference/units/category.rst b/docs/reference/units/category.rst
@@ -15,10 +15,14 @@ Category Fields
 
 There are two fields that are used by the category unit:
 
+.. _Category id field:
+
 ``id``:
     (mandatory) - This field defines the partial identifier of the category. It
     is similar to the ``id`` field on the job definition units.
 
+.. _Category name field:
+
 ``name``:
     (mandatory) - This field defines a human readable name of the category. It
     may be used in application user interfaces for displaying a group of tests.

diff --git a/docs/reference/units/exporter.rst b/docs/reference/units/exporter.rst
@@ -21,26 +21,36 @@ Fields
 
 Following fields may be used by an exporter unit.
 
+.. _Exporter id field:
+
 ``id``:
     (mandatory) - Unique identifier of the exporter. This field is used to look
     up and store data so please keep it stable across the lifetime of your
     provider.
 
+.. _Exporter summary field:
+
 ``summary``:
     (optional) - A human readable name for the exporter. This value is
     available for translation into other languages. It is used when listing
     exporters. It must be one line long, ideally it should be short (50-70
     characters max).
 
+.. _Exporter entry_point field:
+
 ``entry_point``:
     (mandatory) - This is a key for a pkg_resources entry point from the
     plainbox.exporters namespace.
     Allowed values are: jinja2, text, xlsx, json and rfc822.
 
+.. _Exporter file_extension field:
+
 ``file_extension``:
     (mandatory) - Filename extension to use when the exporter stream is saved
     to a file.
 
+.. _Exporter options field:
+
 ``options``:
     (optional) - comma/space/semicolon separated list of options for this
     exporter entry point. Only the following options are currently supported.
@@ -75,6 +85,8 @@ Following fields may be used by an exporter unit.
     jinja2:
         - without-session-desc
 
+.. _Exporter data field:
+
 ``data``:
     (optional) - Extra data sent to the exporter code, to allow all kind of
     data types, the data field only accept valid JSON. For exporters using the

diff --git a/docs/reference/units/job.rst b/docs/reference/units/job.rst
@@ -21,6 +21,8 @@ Job Fields
 
 Following fields may be used by the job unit:
 
+.. _Job id field:
+
 ``id``:
     (mandatory) - A name for the job. Should be unique, an error will
     be generated if there are duplicates. Should contain characters in
@@ -29,16 +31,20 @@ Following fields may be used by the job unit:
     backwards compatibility it is still recognized and used if ``id`` is
     missing.
 
+.. _Job summary field:
+
 ``summary``:
     (mandatory) - A human readable name for the job. This value is available
     for translation into other languages. It is used when listing jobs. It must
     be one line long, ideally it should be short (50-70 characters max).
 
-.. _category_id:
+.. _Job category_id field:
 
 ``category_id``:
     (optional) - Identifier of the :doc:`category` this job belongs to.
 
+.. _Job plugin field:
+
 ``plugin``:
     (mandatory) - For historical reasons it's called "plugin" but it's
     better thought of as describing the "type" of job. The allowed types
@@ -59,6 +65,8 @@ Following fields may be used by the job unit:
           records, containing key/value pairs, and that can be used in other
           jobs' ``requires`` expressions.
 
+.. _Job certification-status field:
+
 ``certification-status``:
     (optional) - Certification status for the given job. This is used by
     Canonical to determine the jobs that **must** be run in order to be able to
@@ -92,6 +100,8 @@ Following fields may be used by the job unit:
         Certification team can evaluate the test report and investigate the
         reasons behind such an outcome.
 
+.. _Job requires field:
+
 ``requires``:
     (optional). If specified, the job will only run if the conditions
     expressed in this field are met.
@@ -107,23 +117,31 @@ Following fields may be used by the job unit:
     respecting the rfc822 multi-line syntax, in which case all
     requirements must be met for the job to run ( ``and`` ed).
 
+.. _Job depends field:
+
 ``depends``:
     (optional). If specified, the job will only run if all the listed
     jobs have run and passed. Multiple job names, separated by spaces,
     can be specified.
 
+.. _Job after field:
+
 ``after``:
     (optional). If specified, the job will only run if all the listed jobs have
     run (regardless of the outcome). Multiple job names, separated by spaces,
     can be specified.
 
     This feature is available since plainbox 0.24.
 
+.. _Job salvages field:
+
 ``salvages``:
     (optional). If specified, the job will only run if all the listed jobs have
     failed. This is useful for obtaining logs from a system when something
     fails. Multiple job names, separated by spaces, can be specified.
 
+.. _Job command field:
+
 ``command``:
     (optional). A command can be provided, to be executed under specific
     circumstances. For ``manual``, ``user-interact`` and ``user-verify``
@@ -140,31 +158,41 @@ Following fields may be used by the job unit:
 
     Note that a ``shell`` job without a command will do nothing.
 
+.. _Job purpose field:
+
 ``purpose``:
     (optional). Purpose field is used in tests requiring human interaction as
     an information about what a given test is supposed to do. User interfaces
     should display content of this field prior to test execution. This field
     may be omitted if the summary field is supplied.
     Note that this field is applicable only for human interaction jobs.
 
+.. _Job steps field:
+
 ``steps``:
     (optional). Steps field depicts actions that user should perform as a part
     of job execution. User interfaces should display the content of this field
     upon starting the test.
     Note that this field is applicable only for jobs requiring the user to
     perform some actions.
 
+.. _Job verification field:
+
 ``verification``:
     (optional). Verification field is used to inform the user how they can
     resolve a given job outcome.
     Note that this field is applicable only for jobs the result of which is
     determined by the user.
 
+.. _Job user field:
+
 ``user``:
     (optional). If specified, the job will be run as the user specified
     here. This is most commonly used to run jobs as the superuser
     (root).
 
+.. _Job environ field:
+
 ``environ``:
     (optional). If specified, the listed environment variables
     (separated by spaces) will be taken from the invoking environment
@@ -178,7 +206,7 @@ Following fields may be used by the job unit:
     environment, with the downside that useful configuration specified
     in environment variables may be lost in the process.
 
-.. _job_estimated_duration:
+.. _Job estimated_duration field:
 
 ``estimated_duration``:
     (optional) This field contains metadata about how long the job is
@@ -200,18 +228,26 @@ Following fields may be used by the job unit:
     say ``2m 30s``). We feel that sub-second granularity does is too
     unpredictable to be useful so that will not be supported in the future.
 
+.. _Job flags field:
+
 ``flags``:
     (optional) This fields contains list of flags separated by spaces or
     commas that might induce plainbox to run the job in particular way.
     Currently, following flags are inspected by plainbox:
 
+    .. _reset-locale flag:
+
     ``reset-locale``:
         This flag makes Checkbox reset locale before running the job.
 
+    .. _win32 flag:
+
     ``win32``:
         This flag makes plainbox run jobs' commands in windows-specific manner.
         Attach this flag to jobs that are run on Windows OS.
 
+    .. _noreturn flag:
+
     ``noreturn``:
         This flag makes plainbox suspend execution after job's command is run.
         This prevents scenario where plainbox continued to operate (writing
@@ -223,13 +259,13 @@ Following fields may be used by the job unit:
         in the ``$PLAINBOX_SESSION_SHARE`` directory which can be used by the
         test to automatically resume session. (For instance after a reboot).
 
-.. _job_flag_explicit_fail:
+    .. _explicit-fail flag:
 
     ``explicit-fail``:
         Use this flag to make entering comment mandatory, when the user
         manually fails the job.
 
-.. _job_flag_has_leftovers:
+    .. _has-leftovers flag:
 
     ``has-leftovers``:
         This flag makes plainbox silently ignore (and not log) any files left
@@ -238,7 +274,7 @@ Following fields may be used by the job unit:
         directories and just want to rely on the one already created by
         plainbox.
 
-.. _job_flag_simple:
+    .. _simple flag:
 
     ``simple``:
         This flag makes plainbox disable certain validation advice and have
@@ -259,31 +295,31 @@ Following fields may be used by the job unit:
             command: echo "Jobs are simple!"
             flags: simple
 
-.. _job_flag_preserve_cwd:
+    .. _preserve-cwd flag:
 
     ``preserve-cwd``:
         This flag makes plainbox run the job command in the current working
         directory without creating a temp folder (and running the command from
         this temp folder). Sometimes needed on snappy
         (See http://pad.lv/1618197)
 
-.. _job_flag_fail_on_resource:
+    .. _fail-on-resource flag:
 
     ``fail-on-resource``:
         This flag makes plainbox fail the job if one of the resource
         requirements evaluates to False.
 
-.. _job_flag_also_after_suspend:
+    .. _also-after-suspend flag:
 
-    ``also-after-suspend``: See ``siblings`` below.
+    ``also-after-suspend``: See :ref:`Job siblings field` below.
 
-.. _job_flag_also_after_suspend_manual:
+    .. _also-after-suspend-manual flag:
 
-    ``also-after-suspend-manual``: See ``siblings`` below.
+    ``also-after-suspend-manual``: See :ref:`Job siblings field` below.
 
     Additional flags may be present in job definition; they are ignored.
 
-.. _job_flag_cachable:
+    .. _cachable flag:
 
     ``cachable``:
         Saves the output of a resource job in the system, so the next time
@@ -292,6 +328,8 @@ Following fields may be used by the job unit:
 
     This flag has no effect on jobs other than resource.
 
+.. _Job siblings field:
+
 ``siblings``:
     (optional) This field creates copies of the current job definition
     but using a dictionary of overridden fields. The intend is to reduce the
@@ -368,6 +406,8 @@ Following fields may be used by the job unit:
                   "depends": "suspend/advanced"}}
                 ]
 
+.. _Job imports field:
+
 ``imports``:
     (optional) This field lists all the resource jobs that will have to be
     imported from other namespaces. This enables jobs to use resources from

diff --git a/docs/reference/units/manifest-entry.rst b/docs/reference/units/manifest-entry.rst
@@ -25,11 +25,15 @@ Fields
 
 Following fields may be used by a manifest entry unit.
 
+.. _Manifest Entry id field:
+
 ``id``:
     (mandatory) - Unique identifier of the entry. This field is used to look up
     and store data so please keep it stable across the lifetime of your
     provider.
 
+.. _Manifest Entry name field:
+
 ``name``:
     (mandatory) - A human readable name of the entry. This should read as in a
     feature matrix of a device in a store (e.g., "802.11ac wireless
@@ -41,22 +45,30 @@ Following fields may be used by a manifest entry unit.
     The name is a translatable field so please prefix it with ``_`` as in
     ``_name: Example``.
 
+.. _Manifest Entry value-type field:
+
 ``value-type``:
     (mandatory) - Type of value for this entry. Currently two values are
     allowed: ``bool`` for a yes/no value and ``natural`` for any natural number
     (negative numbers are rejected).
 
+.. _Manifest Entry value-units field:
+
 ``value-units``:
     (optional) - Units in which value is measured in. This is only used when
     ``value-type`` is equal to ``natural``. For example a *"Screen size"*
     manifest entry could be measured in *"inch"* units.
 
+.. _Manifest Entry resource-key field:
+
 ``resource-key``:
     (optional) - Name of the resource key used to store the manifest value when
     representing the manifest as a resource record. This field defaults to the
     so-called *partial id* which is just the ``id:`` field as spelled in the
     unit definition file (so without the name space of the provider)
 
+.. _Manifest Entry prompt field:
+
 ``prompt``:
     (optional) - Allows the manifest unit to customize the prompt presented
     when collecting values from a user. When the ``value-type`` is ``bool`` the