doc: Update Output processing API docs

doc/source/developer_reference.rst

@@ -15,6 +15,7 @@ Developer Reference
 -----------------
 
 .. include:: developer_reference/output_processing_api.rst
+.. include:: developer_reference/APIs.rst
 
 -----------------
 

doc/source/developer_reference/output_processing_api.rst

@@ -3,14 +3,61 @@
 Output Processing API
 =====================
 
-WA3 now has an output API that can be used to post process a run's
-:ref:`Output Directory Structure<output_directory>` which can be performed by using WA's
-``RunOutput`` object.
+WA3 now has an output API that can be used to post process a runs
+:ref:`Output Directory Structure <output_directory>` which can be performed by using WA's
+:class:`RunOutput` object.
 
-Example:
+This object provides a simple way to access the various aspects of the run. A
+few of the most useful attributes of the ``RunOutput`` object are as follows:
 
-If we have an existing WA output called ``wa_output`` in the current working
-directory we can initialize a ``RunOutput`` as follows:
+- :confval:`jobs` - A list of all the job outputs that were generated for the
+  run. These can be used to used to access more detailed information about
+  individual jobs for example their ``status``, any ``metrics`` or ``artifacts``
+  that were generated etc.
+- :confval:`run_config` - A :ref:`RunConfiguration <run-configuration>` object
+  that can be used to access all the configuration of the run itself, for
+  example the ``reboot_policy``, ``execution_order``, ``device_config`` etc.
+- :confval:`target_info` - A :ref:`TargetInfo <target-info-api>` object which can be used to
+  access various information about the target that was used during the run for
+  example it's ``abi``, ``hostname``, ``os`` etc.
+- :confval:`info` - A :ref:`RunInfo <run-info-api>` object that contains
+  information about the run itself for example it's duration, name, uuid etc.
+- :confval:`settings` - The :ref:`Meta Configuration <meta-configuration>` used
+  during the run.
+- :confval:`status` - The overall status of the run.
+- :confval:`artifacts` - A list containing any run level artifacts (for example
+  logs, output generated by output processors etc.).
+- :confval:`metrics` - A list of :ref:`Metrics <metrics>` that were generated
+  for the overall run.
+- :confval:`classifiers` - A dict mapping of any run level
+  :ref:`classifiers  <classifiers>`.
+- :confval:`augmentations` - A list of the augmentations that were enabled
+  during the run.
+- :confval:`event_summary` - A condensed summary of any events that occurred
+  during the run.
+- :confval:`events` - A list of any events that occurred during the run like job
+  failures etc.
+- :confval:`basepath` - The name of the base WA output directory.
+- :confval:`configfile` - The relative file path to the config file generated
+  for the run.
+- :confval:`failed_dir` - The relative file path to the directory containing any
+  failed jobs during the run.
+- :confval:`infofile` - The file location of the json serialized file of the
+  :class:`RunInfo` object.
+- :confval:`list_workloads()` - A method that generated a list of the workload
+  names that were executed during the run.
+- :confval:`logfile` - A relative file path to the run log.
+- :confval:`metadir` - A relative file path to the metadata directory.
+- :confval:`targetfile` - The file location of the json serialized file of the
+  :class:`TargetInfo` object.
+
+
+Output Processing API Example
+------------------------------
+
+To demonstrate how we can use the output API if we have an existing WA output
+called ``wa_output`` in the current working directory we can initialize a
+``RunOutput`` as follows:
 
 .. code-block:: python