From bde3df81729e64441c36b63c4129567ce5b50583 Mon Sep 17 00:00:00 2001 From: Marc Bonnici 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 ` 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 ` 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 ` 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 ` object that contains + information about the run itself for example it's duration, name, uuid etc. +- :confval:`settings` - The :ref:`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 ` that were generated + for the overall run. +- :confval:`classifiers` - A dict mapping of any run level + :ref:`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 ` 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 ` 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 ` 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 ` object that contains - information about the run itself for example it's duration, name, uuid etc. -- :confval:`settings` - The :ref:`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 ` that were generated - for the overall run. -- :confval:`classifiers` - A dict mapping of any run level - :ref:`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