From 23eb42882925fc0bf3005becd8cc7db6903bab46 Mon Sep 17 00:00:00 2001 From: Marc Bonnici Date: Mon, 25 Jun 2018 10:33:41 +0100 Subject: [PATCH] doc: Add additional references and formatting --- .../developer_guide/writing_plugins.rst | 4 +++- .../developer_reference/execution_model.rst | 6 +++--- .../developer_reference/plugins.rst | 11 ++++++----- .../developer_reference/revent.rst | 8 ++++---- .../developer_information/how_tos/adding_plugins.rst | 1 + 5 files changed, 17 insertions(+), 13 deletions(-) diff --git a/doc/source/developer_information/developer_guide/writing_plugins.rst b/doc/source/developer_information/developer_guide/writing_plugins.rst index f44f84db..12c9ae1a 100644 --- a/doc/source/developer_information/developer_guide/writing_plugins.rst +++ b/doc/source/developer_information/developer_guide/writing_plugins.rst @@ -610,7 +610,9 @@ results in a few common formats (such as csv or JSON). You can add your own output processors by creating a Python file in ``~/.workload_automation/plugins`` with a class that derives from :class:`wa.OutputProcessor `, and should -implement the relevant methods from the following interface: +implement the relevant methods shown below, for more information and please +see the +:ref:`Adding an Output Processor ` section. :name: diff --git a/doc/source/developer_information/developer_reference/execution_model.rst b/doc/source/developer_information/developer_reference/execution_model.rst index 9ad218bc..9dfa450f 100644 --- a/doc/source/developer_information/developer_reference/execution_model.rst +++ b/doc/source/developer_information/developer_reference/execution_model.rst @@ -109,9 +109,9 @@ Signal Dispatch WA uses the `louie `_ (formerly, pydispatcher) library for signal dispatch. Callbacks can be registered for signals emitted during the run. WA uses a version of louie that has been -modified to introduce priority to registered callbacks (so that callbacks that -are know to be slow can be registered with a lower priority and therefore do not -interfere with other callbacks). +modified to introduce :ref:`priority ` to registered callbacks +(so that callbacks that are know to be slow can be registered with a lower +priority and therefore do not interfere with other callbacks). This mechanism is abstracted for instruments. Methods of an :class:`wa.framework.Instrument` subclass automatically get hooked to diff --git a/doc/source/developer_information/developer_reference/plugins.rst b/doc/source/developer_information/developer_reference/plugins.rst index 638ff9fa..bb1e11ac 100644 --- a/doc/source/developer_information/developer_reference/plugins.rst +++ b/doc/source/developer_information/developer_reference/plugins.rst @@ -50,7 +50,7 @@ This is what WA uses to store a single metric collected from executing a workloa metric beyond current iteration (e.g. this can be used to identify sub-tests). -Metrics can be added to WA output via the context: +Metrics can be added to WA output via the :ref:`context `: .. code-block:: python @@ -60,7 +60,7 @@ Metrics can be added to WA output via the context: You only need to specify the name and the value for the metric. Units and classifiers are optional, and, if not specified otherwise, it will be assumed -that higher values are better (lower_is_better=False). +that higher values are better (``lower_is_better=False``). The metric will be added to the result for the current job, if there is one; otherwise, it will be added to the overall run result. @@ -112,7 +112,7 @@ also helps WA decide how it should be handled. Currently supported kinds are: processing -- this is left entirely up to the output processors. -As with :ref:`metrics`, artifacts are added via the context: +As with :ref:`metrics`, artifacts are added via the :ref:`context `: .. code-block:: python @@ -237,6 +237,7 @@ These are specific differences in how they are handled: global run levels); metadata is associated with a particular job or run, and not with metrics or artifacts. +-------------------- .. _execution-decorators: @@ -280,10 +281,10 @@ The specified method will be invoked only once within the environment. normal propagation to be retained. - +-------------------- Utils -^^^^^ +----- Workload Automation defines a number of utilities collected under :mod:`wa.utils` subpackage. These utilities were created to help with the diff --git a/doc/source/developer_information/developer_reference/revent.rst b/doc/source/developer_information/developer_reference/revent.rst index faea285c..0023ab6f 100644 --- a/doc/source/developer_information/developer_reference/revent.rst +++ b/doc/source/developer_information/developer_reference/revent.rst @@ -120,7 +120,7 @@ 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 +General Recording ^^^^^^^^^^^^^^^^^ .. note:: This is the only format supported prior to version ``2``. @@ -158,7 +158,7 @@ path is *not* NULL-terminated. +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -gamepad recording +Gamepad Recording ^^^^^^^^^^^^^^^^^ The recording has been made from a specific gamepad. All events in the stream @@ -240,7 +240,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 @@ -282,7 +282,7 @@ and start and end times for the recording. +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -Event structure +Event Structure ^^^^^^^^^^^^^^^ Each event entry structured as follows: diff --git a/doc/source/developer_information/how_tos/adding_plugins.rst b/doc/source/developer_information/how_tos/adding_plugins.rst index 8d1209f7..8c1ffa8c 100644 --- a/doc/source/developer_information/how_tos/adding_plugins.rst +++ b/doc/source/developer_information/how_tos/adding_plugins.rst @@ -503,6 +503,7 @@ So the full example would look something like:: def finalize(self, context): self.target.uninstall(self.binary_name) +.. _adding-an-output-processor-example: Adding an Output Processor Example ===================================