Add docs for ara_record

These docs are mostly ported as-is from 0.x since the feature hasn't
really changed from a user standpoint.

Change-Id: I4704ef74780c161dc8900b83c93f6ca385fc460a

doc/source/ara-record.rst

@@ -0,0 +1,73 @@
+Recording arbitrary data in playbooks
+=====================================
+
+ARA comes with a built-in Ansible action plugin called ``ara_record``.
+
+This module can be used as an action for a task in your Ansible playbooks in
+order to register whatever you'd like in a key/value format, for example:
+
+.. code-block:: yaml
+
+    - name: Test playbook
+      hosts: localhost
+      tasks:
+        - name: Get git version of playbooks
+          command: git rev-parse HEAD
+          register: git_version
+
+        - name: Record git version
+          ara_record:
+            key: "git_version"
+            value: "{{ git_version.stdout }}"
+          register: version
+
+        - name: Print recorded data
+          debug:
+            msg: "{{ version.playbook_id }} - {{ version.key }}: {{ version.value }}
+
+It also supports different types of data which will have an impact on how a
+value might later be parsed or displayed:
+
+.. code-block:: yaml
+
+    - name: Record different things
+      ara_record:
+        key: "{{ item.key }}"
+        value: "{{ item.value }}"
+        type: "{{ item.type }}"
+      loop:
+        - { key: "log", value: "error", type: "text" }
+        - { key: "website", value: "http://domain.tld", type: "url" }
+        - { key: "data", value: '{ "key": "value" }', type: "json" }
+        - { key: "somelist", value: ['one', 'two'], type: "list" }
+        - { key: "somedict", value: {'key': 'value' }, type: "dict" }
+
+Recording data for playbooks after completion
+---------------------------------------------
+
+It is possible to run an ``ara_record`` task on a specific playbook that might
+already be completed by specifying a playbook. This is particularly useful for
+recording data that might only be available or computed after your playbook run
+has been completed:
+
+.. code-block:: yaml
+
+    ---
+    # Write data to a specific (previously run) playbook
+    - ara_record:
+        playbook: 14
+        key: logs
+        value: "{{ lookup('file', '/var/log/ansible.log') }}"
+        type: text
+
+Or as an ad-hoc command:
+
+.. code-block:: bash
+
+    ansible localhost -m ara_record \
+            -a "playbook=14 key=logs value={{ lookup('file', '/var/log/ansible.log') }}"
+
+This data will be recorded inside ARA's database and associated with the
+particular playbook run that was executed.
+
+These records can later be retrieved through the API or through a web interface.

doc/source/index.rst

@@ -16,6 +16,7 @@ Table of Contents
     API: Endpoint documentation <api-documentation>
     API: Usage with built-in clients <api-usage>
     Setting playbook names and labels <playbook-names-and-labels>
+    Recording arbitrary data in playbooks <ara-record>
     Architecture and workflows <architecture>
 
 .. toctree::