doc: Update heading underlines

Ensure consistency for title levels throughout documentation.

doc/source/api/workload.rst

@@ -1,11 +1,11 @@
 .. _workloads-api:
 
 Workloads
-^^^^^^^^^
+~~~~~~~~~
 .. _workload-api:
 
 Workload
-""""""""
+^^^^^^^^
 
 The base :class:`Workload` interface is as follows, and is the base class for
 all :ref:`workload types <workload-types>`. For more information about to
@@ -39,7 +39,7 @@ All instances of a workload will have the following attributes:
     found by the resource getters
 
 methods
-~~~~~~~
+"""""""
 
 .. method:: Workload.init_resources(context)
 
@@ -155,7 +155,7 @@ methods
 .. _apkworkload-api:
 
 ApkWorkload
-""""""""""""
+^^^^^^^^^^^^
 
 The :class:`ApkWorkload` derives from the base :class:`Workload` class however
 this associates the workload with a package allowing for an apk to be found for
@@ -197,7 +197,7 @@ methods.
 .. _apkuiautoworkload-api:
 
 ApkUiautoWorkload
-"""""""""""""""""
+^^^^^^^^^^^^^^^^^
 
 The :class:`ApkUiautoWorkload` derives from :class:`ApkUIWorkload` which is an
 intermediate class which in turn inherits from
@@ -215,7 +215,7 @@ This class define these additional attributes:
 .. _apkreventworkload-api:
 
 ApkReventWorkload
-"""""""""""""""""
+^^^^^^^^^^^^^^^^^
 
 The :class:`ApkReventWorkload` derives from :class:`ApkUIWorkload` which is an
 intermediate class which in turn inherits from
@@ -245,7 +245,7 @@ This class define these additional attributes:
 .. _uiautoworkload-api:
 
 UiautoWorkload
-""""""""""""""
+^^^^^^^^^^^^^^
 
 The :class:`UiautoWorkload` derives from :class:`UIWorkload` which is an
 intermediate class which in turn inherits from
@@ -263,7 +263,7 @@ This class define these additional attributes:
 .. _reventworkload-api:
 
 ReventWorkload
-""""""""""""""
+^^^^^^^^^^^^^^
 
 The :class:`ReventWorkload` derives from :class:`UIWorkload` which is an
 intermediate class which in turn inherits from

doc/source/developer_information/developer_guide.rst

@@ -1,8 +1,8 @@
 .. _developer_guide:
 
-********************
+***************
 Developer Guide
-********************
+***************
 
 .. contents::
    :depth: 3

doc/source/developer_information/developer_guide/writing_plugins.rst

@@ -37,7 +37,7 @@ proceeding onto guidance for specific plugin types.
 .. _resource-resolution:
 
 Dynamic Resource Resolution
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The idea is to decouple resource identification from resource discovery.
 Workloads/instruments/devices/etc state *what* resources they need, and not
@@ -85,7 +85,7 @@ Currently available resource types are defined in :py:mod:`wa.framework.resource
 .. _deploying-executables:
 
 Deploying executables to a target
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Some targets may have certain restrictions on where executable binaries may be
 placed and how they should be invoked. To ensure your plugin works with as
@@ -237,7 +237,7 @@ iteration). The full list of available methods can be found in
 .. _prioritization:
 
 Prioritization
-^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~
 
 Callbacks (e.g. ``setup()`` methods) for all instruments get executed at the
 same point during workload execution, one after another. The order in which the
@@ -422,7 +422,7 @@ could be a file path), or ``None`` if this getter was unable to discover
 that resource.
 
 Getter Prioritization
-^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~
 
 A priority is an integer with higher numeric values indicating a higher
 priority. The following standard priority aliases are defined for getters:
@@ -450,7 +450,7 @@ there is a good reason). Any integer is a valid priority. The standard prioritie
 range from 0 to 40 in increments of 10.
 
 Example
-^^^^^^^
+~~~~~~~
 
 The following is an implementation of a getter that searches for files in the
 users dependencies directory, typically

doc/source/developer_information/developer_reference/plugins.rst

@@ -35,7 +35,7 @@ This section contains reference information common to plugins of all types.
 .. _context:
 
 The Context
-^^^^^^^^^^^
+~~~~~~~~~~~
 
 The majority of methods in plugins accept a context argument. This is an
 instance of :class:`wa.framework.execution.ExecutionContext`. It contains
@@ -93,7 +93,7 @@ In addition to these, context also defines a few useful paths (see below).
 
 
 Paths
-^^^^^
+~~~~~
 
 You should avoid using hard-coded absolute paths in your plugins whenever
 possible, as they make your code too dependent on a particular environment and
@@ -103,7 +103,7 @@ standard locations. You should strive to define your paths relative
 to one of these.
 
 On the host
-~~~~~~~~~~~
+^^^^^^^^^^^
 
 Host paths are available through the context object, which is passed to most
 plugin methods.
@@ -129,7 +129,7 @@ As per Python best practice, it is recommended that methods and values in
 ``os.path`` standard library module are used for host path manipulation.
 
 On the target
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 
 Workloads and instruments have a ``target`` attribute, which is an interface to
 the target used by WA. It defines the following location:
@@ -158,7 +158,7 @@ irrespective of the host's path notation. For example:
 .. _plugin-parmeters:
 
 Parameters
-^^^^^^^^^^^
+~~~~~~~~~~~
 
 All plugins can be parametrized. Parameters are specified using
 ``parameters`` class attribute. This should be a list of
@@ -227,7 +227,7 @@ specified on parameter creation:
 
 
 Validation and cross-parameter constraints
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 A plugin will get validated at some point after construction. When exactly
 this occurs depends on the plugin type, but it *will* be validated before it
@@ -252,7 +252,7 @@ the parameters. In that case the dependent attribute should be left unspecified
 on creation and should instead be set inside ``validate``.
 
 Logging
-^^^^^^^
+~~~~~~~
 
 Every plugin class has it's own logger that you can access through
 ``self.logger`` inside the plugin's methods. Generally, a :class:`Target` will
@@ -266,7 +266,7 @@ amount of time, such as downloading a file.
 
 
 Documenting
-^^^^^^^^^^^
+~~~~~~~~~~~
 
 All plugins and their parameter should be documented. For plugins
 themselves, this is done through ``description`` class attribute. The convention
@@ -295,7 +295,7 @@ plugin expects (including what the valid values are).
 
 
 Error Notification
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 
 When you detect an error condition, you should raise an appropriate exception to
 notify the user. The exception would typically be :class:`ConfigError` or
@@ -318,7 +318,7 @@ plugin's logger and to continue operation.
 .. _metrics:
 
 Metrics
-^^^^^^^
+~~~~~~~
 This is what WA uses to store a single metric collected from executing a workload.
 
     :name: the name of the metric. Uniquely identifies the metric
@@ -351,7 +351,7 @@ otherwise, it will be added to the overall run result.
 .. _artifact:
 
 Artifacts
-^^^^^^^^^
+~~~~~~~~~
 This is an artifact generated during execution/post-processing of a workload.
 Unlike :ref:`metrics <metrics>`, this represents an actual artifact, such as a
 file, generated.  This may be "output", such as trace, or it could be "meta
@@ -424,7 +424,7 @@ artifact is written to the output directory for the run and not the current job.
 .. _metadata:
 
 Metadata
-^^^^^^^^
+~~~~~~~~
 
 There may be additional data collected by your plugin that you want to record as
 part of the result, but that does not fall under the definition of a "metric".
@@ -473,7 +473,7 @@ specifically to ensure that the entry does not exist at the time of the call.
 .. _classifiers:
 
 Classifiers
-^^^^^^^^^^^
+~~~~~~~~~~~
 
 Classifiers are key-value pairs of tags that can be attached to metrics,
 artifacts, jobs, or the entire run. Run and job classifiers get propagated to
@@ -494,7 +494,7 @@ additional classifiers, by specifying them in ``add_metric()`` and
 
 
 Metadata vs Classifiers
-^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~
 
 Both metadata and classifiers are sets of essentially opaque key-value pairs
 that get included in WA output. While they may seem somewhat similar and
@@ -544,17 +544,17 @@ once, we would use the decorator as follows:
         # ..
 
 @once_per_instance
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 The specified method will be invoked only once for every bound instance within
 the environment.
 
 @once_per_class
-^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~
 The specified method will be invoked only once for all instances of a class
 within the environment.
 
 @once
-^^^^^
+~~~~~
 The specified method will be invoked only once within the environment.
 
 .. warning:: If a method containing a super call is decorated, this will also cause
@@ -601,7 +601,7 @@ information please see `the context`_ documentation. ::
 .. _workload-types:
 
 Workload Types
-^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~
 
 There are multiple workload types that you can inherit from depending on the
 purpose of your workload, the different types along with an output of their
@@ -610,7 +610,7 @@ intended use cases are outlined below.
 .. _basic-workload:
 
 Basic (:class:`wa.Workload <wa.framework.workload.Workload>`)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 This type of the workload is the simplest type of workload and is left the to
 developer to implement its full functionality.
 
@@ -618,7 +618,7 @@ developer to implement its full functionality.
 .. _apk-workload:
 
 Apk (:class:`wa.ApkWorkload <wa.framework.workload.ApkWorkload>`)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 This workload will simply deploy and launch an android app in its basic form
 with no UI interaction.
 
@@ -626,7 +626,7 @@ with no UI interaction.
 
 
 UiAuto (:class:`wa.UiautoWorkload <wa.framework.workload.UiautoWorkload>`)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 This workload is for android targets which will use UiAutomator to interact with
 UI elements without a specific android app, for example performing manipulation
 of android itself. This is the preferred type of automation as the results are
@@ -636,7 +636,7 @@ appear rather than having to rely on human recordings.
 .. _apkuiautomator-workload:
 
 ApkUiAuto (:class:`wa.ApkUiautoWorkload <wa.framework.workload.ApkUiautoWorkload>`)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 The is the same as the UiAuto workload however it is also associated with an
 android app e.g. AdobeReader and will automatically deploy and launch the
 android app before running the automation.
@@ -644,7 +644,7 @@ android app before running the automation.
 .. _revent-workload:
 
 Revent (:class:`wa.ReventWorkload <wa.framework.workload.ReventWorkload>`)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Revent workloads are designed primarily for games as these are unable to be
 automated with UiAutomator due to the fact that they are rendered within a
 single UI element. They require a recording to be performed manually and
@@ -654,7 +654,7 @@ information on revent workloads been please see :ref:`revent_files_creation`
 .. _apkrevent-workload:
 
 APKRevent (:class:`wa.ApkReventWorkload <wa.framework.workload.ApkReventWorkload>`)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 The is the same as the Revent workload however it is also associated with an
 android app e.g. AngryBirds and will automatically deploy and launch the android
 app before running the automation.

doc/source/developer_information/developer_reference/revent.rst

@@ -49,7 +49,7 @@ section is intended for those looking to extend revent in some way, or to
 utilize revent recordings for other purposes.
 
 Format Overview
-^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~
 
 Recordings are stored in a binary format. A recording consists of three
 sections::
@@ -79,7 +79,7 @@ All fields are either fixed size or prefixed with their length or the number of
 
 
 Recording Header
-^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~
 
 An revent recoding header has the following structure
 
@@ -115,13 +115,13 @@ An revent recoding header has the following structure
 
 
 Device Description
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 
 This section describes the input devices used in the recording. Its structure is
 determined by the value of ``Mode`` field in the header.
 
 General Recording
-^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~
 
 .. note:: This is the only format supported prior to version ``2``.
 
@@ -159,7 +159,7 @@ path is *not* NULL-terminated.
 
 
 Gamepad Recording
-^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~
 
 The recording has been made from a specific gamepad. All events in the stream
 will be for that device only. The section describes the device properties that
@@ -241,7 +241,7 @@ determined by the ``abs_bits`` field.
 
 
 Event Stream
-^^^^^^^^^^^^
+~~~~~~~~~~~~
 
 The majority of an revent recording will be made up of the input events that were
 recorded. The event stream is prefixed with the number of events in the stream,
@@ -283,7 +283,7 @@ and start and end times for the recording.
 
 
 Event Structure
-^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~
 
 Each event entry structured as follows:
 
@@ -322,7 +322,7 @@ https://www.kernel.org/doc/Documentation/input/event-codes.txt
 
 
 Parser
-^^^^^^
+~~~~~~
 
 WA has a parser for revent recordings. This can be used to work with revent
 recordings in scripts. Here is an example: