sascha/workload-automation
1
0
Fork 0
mirror of https://github.com/ARM-software/workload-automation.git synced 2025-01-31 10:11:17 +00:00
Code Issues Releases Wiki Activity

doc: Update heading underlines

Browse Source 
Ensure consistency for title levels throughout documentation.
This commit is contained in:
Marc Bonnici 2018-06-29 10:37:56 +01:00 committed by setrofim
parent 98bd3e09b2
commit c67994260d
5 changed files with 47 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
doc/source/api/workload.rst
View File

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

4
doc/source/developer_information/developer_guide.rst
View File

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

10
doc/source/developer_information/developer_guide/writing_plugins.rst
View File

@ -37,7 +37,7 @@ proceeding onto guidance for specific plugin types.
.. _resource-resolution: .. _resource-resolution:
Dynamic Resource Resolution Dynamic Resource Resolution
^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
The idea is to decouple resource identification from resource discovery. The idea is to decouple resource identification from resource discovery.
Workloads/instruments/devices/etc state *what* resources they need, and not 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:
Deploying executables to a target Deploying executables to a target
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some targets may have certain restrictions on where executable binaries may be 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 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:
Prioritization Prioritization
^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~
Callbacks (e.g. ``setup()`` methods) for all instruments get executed at the 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 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. that resource.
Getter Prioritization Getter Prioritization
^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~
A priority is an integer with higher numeric values indicating a higher A priority is an integer with higher numeric values indicating a higher
priority. The following standard priority aliases are defined for getters: 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. range from 0 to 40 in increments of 10.
Example Example
^^^^^^^ ~~~~~~~
The following is an implementation of a getter that searches for files in the The following is an implementation of a getter that searches for files in the
users dependencies directory, typically users dependencies directory, typically

48
doc/source/developer_information/developer_reference/plugins.rst
View File

@ -35,7 +35,7 @@ This section contains reference information common to plugins of all types.
.. _context: .. _context:
The Context The Context
^^^^^^^^^^^ ~~~~~~~~~~~
The majority of methods in plugins accept a context argument. This is an The majority of methods in plugins accept a context argument. This is an
instance of :class:`wa.framework.execution.ExecutionContext`. It contains 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 Paths
^^^^^ ~~~~~
You should avoid using hard-coded absolute paths in your plugins whenever 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 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. to one of these.
On the host On the host
~~~~~~~~~~~ ^^^^^^^^^^^
Host paths are available through the context object, which is passed to most Host paths are available through the context object, which is passed to most
plugin methods. 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. ``os.path`` standard library module are used for host path manipulation.
On the target On the target
~~~~~~~~~~~~~ ^^^^^^^^^^^^^
Workloads and instruments have a ``target`` attribute, which is an interface to Workloads and instruments have a ``target`` attribute, which is an interface to
the target used by WA. It defines the following location: 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: .. _plugin-parmeters:
Parameters Parameters
^^^^^^^^^^^ ~~~~~~~~~~~
All plugins can be parametrized. Parameters are specified using All plugins can be parametrized. Parameters are specified using
``parameters`` class attribute. This should be a list of ``parameters`` class attribute. This should be a list of
@ -227,7 +227,7 @@ specified on parameter creation:
Validation and cross-parameter constraints Validation and cross-parameter constraints
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A plugin will get validated at some point after construction. When exactly 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 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``. on creation and should instead be set inside ``validate``.
Logging Logging
^^^^^^^ ~~~~~~~
Every plugin class has it's own logger that you can access through 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 ``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 Documenting
^^^^^^^^^^^ ~~~~~~~~~~~
All plugins and their parameter should be documented. For plugins All plugins and their parameter should be documented. For plugins
themselves, this is done through ``description`` class attribute. The convention themselves, this is done through ``description`` class attribute. The convention
@ -295,7 +295,7 @@ plugin expects (including what the valid values are).
Error Notification Error Notification
^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~
When you detect an error condition, you should raise an appropriate exception to When you detect an error condition, you should raise an appropriate exception to
notify the user. The exception would typically be :class:`ConfigError` or notify the user. The exception would typically be :class:`ConfigError` or
@ -318,7 +318,7 @@ plugin's logger and to continue operation.
.. _metrics: .. _metrics:
Metrics Metrics
^^^^^^^ ~~~~~~~
This is what WA uses to store a single metric collected from executing a workload. 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 :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: .. _artifact:
Artifacts Artifacts
^^^^^^^^^ ~~~~~~~~~
This is an artifact generated during execution/post-processing of a workload. This is an artifact generated during execution/post-processing of a workload.
Unlike :ref:`metrics <metrics>`, this represents an actual artifact, such as a 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 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:
Metadata Metadata
^^^^^^^^ ~~~~~~~~
There may be additional data collected by your plugin that you want to record as 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". 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 Classifiers
^^^^^^^^^^^ ~~~~~~~~~~~
Classifiers are key-value pairs of tags that can be attached to metrics, 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 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 Metadata vs Classifiers
^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~
Both metadata and classifiers are sets of essentially opaque key-value pairs 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 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 @once_per_instance
^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~
The specified method will be invoked only once for every bound instance within The specified method will be invoked only once for every bound instance within
the environment. the environment.
@once_per_class @once_per_class
^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~
The specified method will be invoked only once for all instances of a class The specified method will be invoked only once for all instances of a class
within the environment. within the environment.
@once @once
^^^^^ ~~~~~
The specified method will be invoked only once within the environment. 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 .. 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:
Workload Types Workload Types
^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~
There are multiple workload types that you can inherit from depending on the 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 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-workload:
Basic (:class:`wa.Workload <wa.framework.workload.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 This type of the workload is the simplest type of workload and is left the to
developer to implement its full functionality. developer to implement its full functionality.
@ -618,7 +618,7 @@ developer to implement its full functionality.
.. _apk-workload: .. _apk-workload:
Apk (:class:`wa.ApkWorkload <wa.framework.workload.ApkWorkload>`) Apk (:class:`wa.ApkWorkload <wa.framework.workload.ApkWorkload>`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This workload will simply deploy and launch an android app in its basic form This workload will simply deploy and launch an android app in its basic form
with no UI interaction. with no UI interaction.
@ -626,7 +626,7 @@ with no UI interaction.
UiAuto (:class:`wa.UiautoWorkload <wa.framework.workload.UiautoWorkload>`) UiAuto (:class:`wa.UiautoWorkload <wa.framework.workload.UiautoWorkload>`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This workload is for android targets which will use UiAutomator to interact with This workload is for android targets which will use UiAutomator to interact with
UI elements without a specific android app, for example performing manipulation 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 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: .. _apkuiautomator-workload:
ApkUiAuto (:class:`wa.ApkUiautoWorkload <wa.framework.workload.ApkUiautoWorkload>`) ApkUiAuto (:class:`wa.ApkUiautoWorkload <wa.framework.workload.ApkUiautoWorkload>`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The is the same as the UiAuto workload however it is also associated with an 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 e.g. AdobeReader and will automatically deploy and launch the
android app before running the automation. android app before running the automation.
@ -644,7 +644,7 @@ android app before running the automation.
.. _revent-workload: .. _revent-workload:
Revent (:class:`wa.ReventWorkload <wa.framework.workload.ReventWorkload>`) Revent (:class:`wa.ReventWorkload <wa.framework.workload.ReventWorkload>`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Revent workloads are designed primarily for games as these are unable to be 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 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 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-workload:
APKRevent (:class:`wa.ApkReventWorkload <wa.framework.workload.ApkReventWorkload>`) APKRevent (:class:`wa.ApkReventWorkload <wa.framework.workload.ApkReventWorkload>`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The is the same as the Revent workload however it is also associated with an 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 android app e.g. AngryBirds and will automatically deploy and launch the android
app before running the automation. app before running the automation.

16
doc/source/developer_information/developer_reference/revent.rst
View File

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