diff --git a/doc/source/api/workload.rst b/doc/source/api/workload.rst index 26ac4bec..468516b8 100644 --- a/doc/source/api/workload.rst +++ b/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 `. 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 diff --git a/doc/source/developer_information/developer_guide.rst b/doc/source/developer_information/developer_guide.rst index 44565732..ddd33b80 100644 --- a/doc/source/developer_information/developer_guide.rst +++ b/doc/source/developer_information/developer_guide.rst @@ -1,8 +1,8 @@ .. _developer_guide: -******************** +*************** Developer Guide -******************** +*************** .. contents:: :depth: 3 diff --git a/doc/source/developer_information/developer_guide/writing_plugins.rst b/doc/source/developer_information/developer_guide/writing_plugins.rst index 57451b08..6abe127c 100644 --- a/doc/source/developer_information/developer_guide/writing_plugins.rst +++ b/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 diff --git a/doc/source/developer_information/developer_reference/plugins.rst b/doc/source/developer_information/developer_reference/plugins.rst index 7c342d0d..8f48f2f6 100644 --- a/doc/source/developer_information/developer_reference/plugins.rst +++ b/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 `, 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 `) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 `) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 `) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 `) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 `) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 `) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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. diff --git a/doc/source/developer_information/developer_reference/revent.rst b/doc/source/developer_information/developer_reference/revent.rst index 0023ab6f..81950ec0 100644 --- a/doc/source/developer_information/developer_reference/revent.rst +++ b/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: