diff --git a/doc/source/developer_reference.rst b/doc/source/developer_reference.rst index aad91653..f38ce632 100644 --- a/doc/source/developer_reference.rst +++ b/doc/source/developer_reference.rst @@ -15,6 +15,7 @@ Developer Reference ----------------- .. include:: developer_reference/output_processing_api.rst +.. include:: developer_reference/APIs.rst ----------------- diff --git a/doc/source/developer_reference/output_processing_api.rst b/doc/source/developer_reference/output_processing_api.rst index 47a018e5..a02587cc 100644 --- a/doc/source/developer_reference/output_processing_api.rst +++ b/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` 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 ` 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 ` 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 +``RunOutput`` as follows: .. code-block:: python