sascha/workload-automation
1
0
Fork 0
mirror of https://github.com/ARM-software/workload-automation.git synced 2025-01-18 20:11:20 +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
^^^^^^^^^
~~~~~~~~~
.. _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

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

@ -1,8 +1,8 @@
.. _developer_guide:
********************
***************
Developer Guide
********************
***************
.. contents::
: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:
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

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:
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.

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.
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: