docs: Update to include Collector information

doc/collectors.rst

@@ -0,0 +1,153 @@
+.. _collector:
+
+Collectors
+==========
+
+The ``Collector`` API provide a consistent way of collecting arbitrary data from
+a target. Data is collected via an instance of a class derived from
+:class:`CollectorBase`.
+
+
+Example
+-------
+
+The following example shows how to use a collector to read the logcat output
+from an Android target.
+
+.. code-block:: python
+
+    # import and instantiate the Target and the collector
+    # (note: this assumes exactly one android target connected
+    #  to the host machine).
+    In [1]: from devlib import AndroidTarget, LogcatCollector
+
+    In [2]: t = AndroidTarget()
+
+    # Set up the collector on the Target.
+
+    In [3]: collector = LogcatCollector(t)
+
+    # Configure the output file path for the collector to use.
+    In [4]: collector.set_output('adb_log.txt')
+
+    # Reset the Collector to preform any required configuration or preparation.
+    In [5]: collector.reset()
+
+    # Start Collecting
+    In [6]: collector.start()
+
+    # Wait for some output to be generated
+    In [7]: sleep(10)
+
+    # Stop Collecting
+    In [8]: collector.stop()
+
+    # Retrieved the collected data
+    In [9]: output = collector.get_data()
+
+    # Display the returned ``CollectorOutput`` Object.
+    In [10]: output
+    Out[10]: [<adb_log.txt (file)>]
+
+    In [11] log_file = output[0]
+
+    # Get the path kind of the the returned CollectorOutputEntry.
+    In [12]: log_file.path_kind
+    Out[12]: 'file'
+
+    # Get the path of the returned CollectorOutputEntry.
+    In [13]: log_file.path
+    Out[13]: 'adb_log.txt'
+
+    # Find the full path to the log file.
+    In [14]: os.path.join(os.getcwd(), logfile)
+    Out[14]: '/tmp/adb_log.txt'
+
+
+API
+---
+.. collector:
+
+.. module:: devlib.collector
+
+
+CollectorBase
+~~~~~~~~~~~~~
+
+.. class:: CollectorBase(target, \*\*kwargs)
+
+   A ``CollectorBase`` is the the base class and API that should be
+   implemented to allowing collecting various data from a traget e.g. traces,
+   logs etc.
+
+.. method::  Collector.setup(\*args, \*\*kwargs)
+
+   This will set up the collector on the target. Parameters this method takes
+   are particular to subclasses (see documentation for specific collectors
+   below).  What actions are performed by this method are also
+   collector-specific.  Usually these will be things like  installing
+   executables, starting services, deploying assets, etc. Typically, this method
+   needs to be invoked at most once per reboot of the target (unless
+   ``teardown()`` has been called), but see documentation for the collector
+   you're interested in.
+
+.. method:: CollectorBase.reset()
+
+   This can be used to configure a collector for collection. This must be invoked
+   before ``start()`` is called to begin collection.
+
+.. method:: CollectorBase.start()
+
+   Starts collecting from the target.
+
+.. method:: CollectorBase.stop()
+
+   Stops collecting from target. Must be called after
+   :func:`start()`.
+
+
+.. method:: CollectorBase.set_output(output_path)
+
+   Configure the output path for the particular collector. This will be either
+   a directory or file path which will be used when storing the data. Please see
+   the individual Collector documentation for more information.
+
+
+.. method:: CollectorBase.get_data()
+
+    The collected data will be return via the previously specified output_path.
+    This method will return a ``CollectorOutput`` object which is a subclassed
+    list object containing individual ``CollectorOutputEntry`` objects with details
+    about the individual output entry.
+
+
+CollectorOutputEntry
+~~~~~~~~~~~~~~~~~~~~
+
+This object is designed to allow for the output of a collector to be processed
+generically. The object will behave as a regular string containing the path to
+underlying output path and can be used directly in ``os.path`` operations.
+
+.. attribute:: CollectorOutputEntry.path
+
+    The file path for the corresponding output item.
+
+.. attribute:: CollectorOutputEntry.path_kind
+
+    The type of output the is specified in the ``path`` attribute. Current valid
+    kinds are: ``file`` and ``directory``.
+
+.. method:: CollectorOutputEntry.__init__(path, path_kind)
+
+    Initialises a ``CollectorOutputEntry`` object with the desired file path and
+    kind of file path specified.
+
+
+.. collectors:
+
+Available Collectors
+---------------------
+
+This section lists collectors that are currently part of devlib.
+
+.. todo:: Add collectors