Add docs for configuring Ansible and ARA plugins

This is ported and adapted from 0.x so users can read how to configure
Ansible to use ARA and how to configure the ARA Ansible plugins.

Change-Id: I021ef773a5bb8e0b1b11cb2a3b8fb6611665e319

doc/source/ansible-configuration.rst

@@ -0,0 +1,59 @@
+Configuring Ansible to use ARA
+==============================
+
+To begin using ARA, you'll first need to tell Ansible where it is located.
+
+Since this location will be different depending on your operating system and
+how you are installing ARA, there are convenient python modules to help you
+figure out the right paths.
+
+Once you've set up the ``callback_plugins`` configuration or the
+``ANSIBLE_CALLBACK_PLUGINS`` environment variable, Ansible will automatically
+use the ARA callback plugin to start recording data.
+
+If you'd like to use the ``ara_record`` action plugin to record arbitrary data
+during your playbook, you'll need to set ``action_plugins`` and
+``ANSIBLE_ACTION_PLUGINS`` as well.
+
+Using setup helper modules
+--------------------------
+
+The modules can be used directly on the command line:
+
+.. code-block:: bash
+
+    $ python3 -m ara.setup.path
+    /usr/lib/python3.7/site-packages/ara
+
+    $ python3 -m ara.setup.plugins
+    /usr/lib/python3.7/site-packages/ara/plugins
+
+    $ python3 -m ara.setup.action_plugins
+    /usr/lib/python3.7/site-packages/ara/plugins/action
+
+    $ python3 -m ara.setup.callback_plugins
+    /usr/lib/python3.7/site-packages/ara/plugins/callback
+
+    # Note: This doesn't export anything, it only prints the commands.
+    # If you want to export directly from the command, you can use:
+    #     source <(python3 -m ara.setup.env)
+    $ python3 -m ara.setup.env
+    export ANSIBLE_CALLBACK_PLUGINS=/usr/lib/python3.7/site-packages/ara/plugins/callback
+    export ANSIBLE_ACTION_PLUGINS=/usr/lib/python3.7/site-packages/ara/plugins/action
+
+    $ python3 -m ara.setup.ansible
+    [defaults]
+    callback_plugins=/usr/lib/python3.7/site-packages/ara/plugins/callback
+    action_plugins=/usr/lib/python3.7/site-packages/ara/plugins/action
+
+Or from python, for example:
+
+.. code-block:: python
+
+    >>> from ara.setup import callback_plugins
+    >>> print(callback_plugins)
+    /usr/lib/python3.7/site-packages/ara/plugins/callback
+
+    >>> from ara.setup import action_plugins
+    >>> print(action_plugins)
+    /usr/lib/python3.7/site-packages/ara/plugins/action

doc/source/ara-plugin-configuration.rst

@@ -0,0 +1,72 @@
+Configuring the ARA Ansible plugins
+===================================
+
+ARA plugins uses the same mechanism and configuration files as Ansible to
+retrieve it's configuration. It comes with sane defaults that can be customized
+if need be.
+
+The order of priority is the following:
+
+1. Environment variables
+2. ``./ansible.cfg`` (*in the current working directory*)
+3. ``~/.ansible.cfg`` (*in the home directory*)
+4. ``/etc/ansible/ansible.cfg``
+
+When using the ``ansible.cfg`` file, the configuration options must be set
+under the ara namespace, like so:
+
+.. code-block:: ini
+
+    [ara]
+    variable = value
+
+ARA callback plugin
+-------------------
+
+The ARA callback plugin is the component that recovers data throughout the
+execution of your playbook and sends it to the API.
+
+By default, the callback plugin is set up to use the local API server with the
+offline API client but you can also send data to a remote API server, specify
+credentials or customize other parameters:
+
+.. literalinclude:: ../../ara/plugins/callback/ara_default.py
+  :language: yaml
+  :start-after: DOCUMENTATION
+  :end-before: """
+
+For example, a customized callback plugin configuration might look like this in
+an ``ansible.cfg`` file:
+
+.. code-block:: ini
+
+    [ara]
+    api_client = http
+    api_server = https://api.demo.recordsansible.org
+    api_username = user
+    api_password = password
+    api_timeout = 15
+    ignored_facts = '["ansible_env", "ansible_all_ipv4_addresses"]'
+    ignored_arguments = '["extra_vars", "vault_password_files"]'
+
+or as environment variables:
+
+.. code-block:: bash
+
+    export ARA_API_CLIENT=http
+    export ARA_API_SERVER="https://api.demo.recordsansible.org"
+    export ARA_API_USERNAME=user
+    export ARA_API_PASSWORD=password
+    export ARA_API_TIMEOUT=15
+    export ARA_IGNORED_FACTS='["ansible_env", "ansible_all_ipv4_addresses"]'
+    export ARA_IGNORED_ARGUMENTS='["extra_vars", "vault_password_files"]'
+
+ARA action plugin: ara_record
+-----------------------------
+
+The ``ara_record`` action plugin recovers it's configuration from the callback
+plugin.
+
+It is therefore not necessary to configure it explicitely other than
+enabling Ansible to find it by setting ``action_plugins`` in ``ansible.cfg`` or
+the ``ANSIBLE_ACTION_PLUGINS`` environment variable.

doc/source/index.rst

@@ -9,10 +9,12 @@ Table of Contents
     :maxdepth: 2
 
     Installing ARA <installation>
-    API configuration settings and preferences <api-configuration>
-    API authentication and security <api-security>
-    API endpoint documentation <api-documentation>
-    API usage with built-in clients <api-usage>
+    Configuring Ansible to use ARA <ansible-configuration>
+    Configuring the ARA Ansible plugins <ara-plugin-configuration>
+    Configuring the ARA API server <api-configuration>
+    API: Authentication and security <api-security>
+    API: Endpoint documentation <api-documentation>
+    API: Usage with built-in clients <api-usage>
     Architecture and workflows <architecture>
 
 .. toctree::