From 03235d0b591a6e48a87777452f3b545fb486e530 Mon Sep 17 00:00:00 2001
From: Sergei Trofimov <sergei.trofimov@arm.com>
Date: Mon, 25 Jun 2018 17:02:13 +0100
Subject: [PATCH] doc: output API restructure part 2

- move TargetInfo and RunInfo docs into the new output API doc
- remove the old developer_reference/APIs.rst as obsolete
- Update output API tag reference to point to the new doc
---
 doc/source/api/output.rst               |  94 +++++++++++++++++++
 doc/source/developer_reference.rst      |   4 -
 doc/source/developer_reference/APIs.rst | 114 ------------------------
 3 files changed, 94 insertions(+), 118 deletions(-)
 delete mode 100644 doc/source/developer_reference/APIs.rst

diff --git a/doc/source/api/output.rst b/doc/source/api/output.rst
index 7f20fcb8..e4212ea1 100644
--- a/doc/source/api/output.rst
+++ b/doc/source/api/output.rst
@@ -1,3 +1,5 @@
+.. _output_processing_api:
+
 Output
 ======
 
@@ -441,3 +443,95 @@ description
 
 classifiers
     Job- and run-level :term:`classifier`\ s will be propagated to the artifact.
+
+
+Additional run info
+-------------------
+
+:class:`RunOutput` object has ``target_info``  and ``run_info`` attributes that
+contain structures that provide additional information about the run and device.
+
+.. _target-info-api:
+
+:class:`TargetInfo`
+~~~~~~~~~~~~~~~~~~~
+
+The :class:`TargetInfo` class presents various pieces of information about the
+target device. An instance of this class will be instantiated and populated
+automatically from the devlib `target
+<http://devlib.readthedocs.io/en/latest/target.html>`_ created during a WA run
+and serialized to a json file as part of the metadata exported
+by WA at the end of a run.
+
+The available attributes of the class are as follows:
+
+target
+    The name of the target class that was uised ot interact with the device
+    during the run E.g.  ``"AndroidTarget"``, ``"LinuxTarget"`` etc.
+
+cpus
+    A list of :class:`CpuInfo` objects describing the capabilities of each CPU.
+
+os
+    A generic name of the OS the target was running (e.g. ``"android"``).
+
+os_version
+    A dict that contains a mapping of OS version elements to their values. This
+    mapping is OS-specific.
+
+abi
+    The ABI of the target device.
+
+hostname
+    The hostname of the the device the run was executed on.
+
+is_rooted
+    A boolean value specifying whether root was detected on the device.
+
+kernel_version
+    The version of the kernel on the target device.  This returns a
+    :class:`KernelVersion` instance that has separate version and release
+    fields.
+
+kernel_config
+    A :class:`KernelConfig` instance that contains parsed kernel config from the
+    target device. This may be ``None`` if the kernel config could not be
+    extracted.
+
+sched_features
+    A list of the available tweaks to the scheduler, if available from the
+    device.
+
+hostid
+    The unique identifier of the particular device the WA run was executed on.
+
+
+.. _run-info-api:
+
+:class:`RunInfo`
+~~~~~~~~~~~~~~~~
+
+The :class:`RunInfo` provides general run information. It has the following
+attributes:
+
+
+uuid
+    A unique identifier for that particular run.
+
+run_name
+    The name of the run (if provided)
+
+project
+    The name of the project the run belongs to (if provided)
+
+project_stage
+    The project stage the run is associated with (if provided)
+
+duration
+    The length of time the run took to complete.
+
+start_time
+    The time the run was stared.
+
+end_time
+    The time at which the run finished.
diff --git a/doc/source/developer_reference.rst b/doc/source/developer_reference.rst
index 3bac067d..fdf74173 100644
--- a/doc/source/developer_reference.rst
+++ b/doc/source/developer_reference.rst
@@ -14,10 +14,6 @@ Developer Reference
 
 -----------------
 
-.. include:: developer_reference/APIs.rst
-
------------------
-
 .. include:: developer_reference/writing_plugins.rst
 
 -----------------
diff --git a/doc/source/developer_reference/APIs.rst b/doc/source/developer_reference/APIs.rst
deleted file mode 100644
index 3dd996f5..00000000
--- a/doc/source/developer_reference/APIs.rst
+++ /dev/null
@@ -1,114 +0,0 @@
-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:
-
-TargetInfo API
----------------
-
-The :class:`TargetInfo` class is designed to provide an easy way of presenting
-various pieces of information about the target device. An instance of this class
-will be instantiated and populated automatically from the devlib
-`target <http://devlib.readthedocs.io/en/latest/target.html>`_ created
-during a WA run and serialized to a json file as part of the metadata exported
-by WA at the end of a run.
-
-The available attributes of the class are as follows:
-
-- :confval:`target` - The name of the target that was created. E.g.
-  AndroidTarget, LinuxTarget etc.
-- :confval:`cpus` - A list of the unique cpu types that have been detected on
-  the target. E.g. 'A53', 'A72' etc.
-- :confval:`os` - The OS that the target was running.
-- :confval:`os_version` - A dict that contains a mapping of OS version elements
-  to their values. This mapping is OS-specific.
-- :confval:`abi` - The ABI of the target device.
-- :confval:`hostname` - The hostname of the the device the run was executed on.
-- :confval:`is_rooted` - A boolean value specifying whether root was detected on
-  the device.
-- :confval:`kernel_version` - The version of the kernel on the target device.
-  This returns a :class:`KernelVersion` instance that has separate version and
-  release fields.
-- :confval:`kernel_config` - A :class:`KernelConfig` instance that contains
-  parsed kernel config from the target device. This may be ``None`` if the
-  kernel config could not be extracted.
-- :confval:`sched_features` - A list of the available tweaks to the scheduler,
-  if available from the device.
-- :confval:`hostid` - The unique identifier of the particular device the WA run
-  was executed on.
-
----------------------
-
-.. _run-info-api:
-
-Run Info API
-------------
-
-The :class:`RunInfo` can be used to provide information about the run in
-general. The available attributes of the class are as follows:
-
-
-- :confval:`uuid` - A unique identifier for that particular run.
-- :confval:`run_name` - The name of the run (if provided)
-- :confval:`project` - The name of the project the run belongs to (if provided)
-- :confval:`project_stage` - The project stage the run is associated with (if provided)
-- :confval:`duration` - The length of time the run took to complete.
-- :confval:`start_time` - The time the run was stared.
-- :confval:`end_time` - The time at which the run finished.