From bde3df81729e64441c36b63c4129567ce5b50583 Mon Sep 17 00:00:00 2001
From: Marc Bonnici <marc.bonnici@arm.com>
Date: Wed, 6 Jun 2018 18:06:29 +0100
Subject: [PATCH] doc: Restructure API documentation
---
doc/source/developer_reference.rst | 1 -
doc/source/developer_reference/APIs.rst | 55 +++++++++++++++++++
..._api.rst => output_processing_example.rst} | 55 +------------------
3 files changed, 56 insertions(+), 55 deletions(-)
rename doc/source/developer_reference/{output_processing_api.rst => output_processing_example.rst} (50%)
diff --git a/doc/source/developer_reference.rst b/doc/source/developer_reference.rst
index f38ce632..3bac067d 100644
--- a/doc/source/developer_reference.rst
+++ b/doc/source/developer_reference.rst
@@ -14,7 +14,6 @@ Developer Reference
-----------------
-.. include:: developer_reference/output_processing_api.rst
.. include:: developer_reference/APIs.rst
-----------------
diff --git a/doc/source/developer_reference/APIs.rst b/doc/source/developer_reference/APIs.rst
index 2408c75b..3dd996f5 100644
--- a/doc/source/developer_reference/APIs.rst
+++ b/doc/source/developer_reference/APIs.rst
@@ -1,6 +1,61 @@
APIs
====
+.. _output_processing_api:
+
+Output Processing API
+---------------------
+
+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.
+
+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:
+
+- :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.
+
+.. include:: developer_reference/output_processing_example.rst
+
---------------------
.. _target-info-api:
diff --git a/doc/source/developer_reference/output_processing_api.rst b/doc/source/developer_reference/output_processing_example.rst
similarity index 50%
rename from doc/source/developer_reference/output_processing_api.rst
rename to doc/source/developer_reference/output_processing_example.rst
index a02587cc..28eecfb0 100644
--- a/doc/source/developer_reference/output_processing_api.rst
+++ b/doc/source/developer_reference/output_processing_example.rst
@@ -1,59 +1,6 @@
-.. _output_processing_api:
-
-Output Processing API
-=====================
-
-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.
-
-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:
-
-- :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