1.0 backport: Add helper modules/scripts to know where ARA is

The location where ARA is installed is hard to predict because it will
depend on the operating system, python2 vs python3 or the usage of
virtualenvs, for example.

That's why we have this rather convenient snippet:
python -c "import os,ara; print(os.path.dirname(ara.__file__))"

This snippet is now further reduced to:
python -m ara.setup.path

But there is also many other variants such as:
- python -m ara.setup.path
- python -m ara.setup.callback_plugins
- python -m ara.setup.action_plugins
- python -m ara.setup.library
- python -m ara.setup.env
- python -m ara.setup.ansible

These can also be imported as such:

from ara.setup import path
from ara.setup import callback_plugins
[...]

This might be expanded upon later but let's stop at this for now.

Change-Id: Ibf1eb495ea0df2f6d8589abeb2220b6e93afdea9
(cherry picked from commit f1e4b5d521)

ara/setup/README.rst

@@ -0,0 +1,5 @@
+This directory contains scripts meant to help configuring ARA with Ansible.
+
+For more information, visit the documentation_.
+
+.. _documentation: http://ara.readthedocs.io/en/latest/configuration.html

ara/setup/__init__.py

@@ -0,0 +1,25 @@
+#  Copyright (c) 2017 Red Hat, Inc.
+#
+#  This file is part of ARA: Ansible Run Analysis.
+#
+#  ARA is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  ARA is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with ARA.  If not, see <http://www.gnu.org/licenses/>.
+
+import os
+
+# The path where ARA is installed (parent directory)
+path = os.path.abspath(os.path.dirname(os.path.dirname(__file__)))
+
+action_plugins = os.path.abspath(os.path.join(path, 'plugins/actions'))
+callback_plugins = os.path.abspath(os.path.join(path, 'plugins/callbacks'))
+library = os.path.abspath(os.path.join(path, 'plugins/modules'))

ara/setup/action_plugins.py

@@ -0,0 +1,22 @@
+#  Copyright (c) 2017 Red Hat, Inc.
+#
+#  This file is part of ARA: Ansible Run Analysis.
+#
+#  ARA is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  ARA is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with ARA.  If not, see <http://www.gnu.org/licenses/>.
+
+from __future__ import print_function
+from . import action_plugins
+
+if __name__ == "__main__":
+    print(action_plugins)

ara/setup/ansible.py

@@ -0,0 +1,29 @@
+#  Copyright (c) 2017 Red Hat, Inc.
+#
+#  This file is part of ARA: Ansible Run Analysis.
+#
+#  ARA is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  ARA is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with ARA.  If not, see <http://www.gnu.org/licenses/>.
+
+from __future__ import print_function
+from . import callback_plugins, action_plugins, library
+
+config = """
+[defaults]
+callback_plugins={}
+action_plugins={}
+library={}
+""".format(callback_plugins, action_plugins, library)
+
+if __name__ == "__main__":
+    print(config.strip())

ara/setup/callback_plugins.py

@@ -0,0 +1,22 @@
+#  Copyright (c) 2017 Red Hat, Inc.
+#
+#  This file is part of ARA: Ansible Run Analysis.
+#
+#  ARA is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  ARA is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with ARA.  If not, see <http://www.gnu.org/licenses/>.
+
+from __future__ import print_function
+from . import callback_plugins
+
+if __name__ == "__main__":
+    print(callback_plugins)

ara/setup/env.py

@@ -0,0 +1,28 @@
+#  Copyright (c) 2017 Red Hat, Inc.
+#
+#  This file is part of ARA: Ansible Run Analysis.
+#
+#  ARA is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  ARA is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with ARA.  If not, see <http://www.gnu.org/licenses/>.
+
+from __future__ import print_function
+from . import callback_plugins, action_plugins, library
+
+exports = """
+export ANSIBLE_CALLBACK_PLUGINS={}
+export ANSIBLE_ACTION_PLUGINS={}
+export ANSIBLE_LIBRARY={}
+""".format(callback_plugins, action_plugins, library)
+
+if __name__ == "__main__":
+    print(exports.strip())

ara/setup/library.py

@@ -0,0 +1,22 @@
+#  Copyright (c) 2017 Red Hat, Inc.
+#
+#  This file is part of ARA: Ansible Run Analysis.
+#
+#  ARA is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  ARA is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with ARA.  If not, see <http://www.gnu.org/licenses/>.
+
+from __future__ import print_function
+from . import library
+
+if __name__ == "__main__":
+    print(library)

ara/setup/path.py

@@ -0,0 +1,22 @@
+#  Copyright (c) 2017 Red Hat, Inc.
+#
+#  This file is part of ARA: Ansible Run Analysis.
+#
+#  ARA is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  ARA is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with ARA.  If not, see <http://www.gnu.org/licenses/>.
+
+from __future__ import print_function
+from . import path
+
+if __name__ == "__main__":
+    print(path)

ara/tests/unit/test_setup.py

@@ -0,0 +1,29 @@
+#  Copyright (c) 2017 Red Hat, Inc.
+#
+#  This file is part of ARA: Ansible Run Analysis.
+#
+#  ARA is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  ARA is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with ARA.  If not, see <http://www.gnu.org/licenses/>.
+
+from ara.tests.unit.common import TestAra
+
+
+class TestSetup(TestAra):
+    """ Tests the utils module """
+    def setUp(self):
+        super(TestSetup, self).setUp()
+
+    def tearDown(self):
+        super(TestSetup, self).tearDown()
+
+    # TODO: Add tests :D

doc/source/configuration.rst

@@ -12,39 +12,47 @@ To begin using ARA, you'll first need to set up Ansible so it knows about the
 the ARA :ref:`callback <faq_callback>` and, if necessary, the :ref:`ara_record <ara_record>` and :ref:`ara_read <ara_read>` modules.
 
 The callback and modules are bundled when installing ARA but you need to know
-where they have been installed in order to let Ansible know where they are located.
+where they have been installed in order to let Ansible know where they are
+located.
 
-.. tip::
+This location will be different depending on your operating system, how you are
+installing ARA and whether you are using Python 2 or Python 3.
 
-   The location where ARA will be depends on your operating system and how it
-   is installed.
-   Here's some examples of where ARA can be found:
+ARA ships a set of convenience Python modules to help you configure Ansible to
+use it.
 
-   - ``/usr/lib/python2.7/site-packages/ara``
-   - ``/usr/lib/python3.5/site-packages/ara``
-   - ``$VIRTUAL_ENV/lib/python2.7/site-packages/ara``
+They can be used like so::
 
-   If you're not sure where ARA will end up being installed, you can use this
-   snippet to print its location. It works in both Python 2 and Python 3::
+    $ python -m ara.setup.path
+    /usr/lib/python2.7/site-packages/ara
 
-      python -c "import os,ara; print(os.path.dirname(ara.__file__))"
+    $ python -m ara.setup.action_plugins
+    /usr/lib/python2.7/site-packages/ara/plugins/actions
+
+    $ python -m ara.setup.callback_plugins
+    /usr/lib/python2.7/site-packages/ara/plugins/callbacks
+
+    $ python -m ara.setup.library
+    /usr/lib/python2.7/site-packages/ara/plugins/modules
 
 Using ansible.cfg
 ~~~~~~~~~~~~~~~~~
 
-Set up your `ansible.cfg`_ file to seek the callback and modules in the appropriate
-directories::
+This sets up a new `ansible.cfg`_ file to load the callbacks and modules from
+the appropriate locations::
 
-    $ export ara_location=$(python -c "import os,ara; print(os.path.dirname(ara.__file__))")
-    $ cat > ansible.cfg <<EOF
+    $ python -m ara.setup.ansible | tee ansible.cfg
     [defaults]
-    # callback_plugins configuration is required for the ARA callback
-    callback_plugins = $ara_location/plugins/callbacks
+    callback_plugins=/usr/lib/python2.7/site-packages/ara/plugins/callbacks
+    action_plugins=/usr/lib/python2.7/site-packages/ara/plugins/actions
+    library=/usr/lib/python2.7/site-packages/ara/plugins/modules
 
-    # action_plugins and library configuration is required for the ara_record and ara_read modules
-    action_plugins = $ara_location/plugins/actions
-    library = $ara_location/plugins/modules
-    EOF
+Or alternatively, if you have a customized `ansible.cfg`_ file, you can retrieve
+only what you need using the other helpers such as the following:
+
+- ``python -m ara.setup.callback_plugins``
+- ``python -m ara.setup.action_plugins``
+- ``python -m ara.setup.library``
 
 .. _ansible.cfg: https://docs.ansible.com/ansible/intro_configuration.html#configuration-file
 
@@ -53,12 +61,16 @@ Using environment variables
 
 Depending on the context and your use case, configuring Ansible using
 `environment variables`_ instead of an ``ansible.cfg`` file might be more convenient.
-Here's how you can set up Ansible to seek out ARA's callback and modules::
 
-    $ export ara_location=$(python -c "import os,ara; print(os.path.dirname(ara.__file__))")
-    $ export ANSIBLE_CALLBACK_PLUGINS=$ara_location/plugins/callbacks
-    $ export ANSIBLE_ACTION_PLUGINS=$ara_location/plugins/actions
-    $ export ANSIBLE_LIBRARY=$ara_location/plugins/modules
+ARA provides a helper module that prints out the necessary export commands::
+
+    $ python -m ara.setup.env
+    export ANSIBLE_CALLBACK_PLUGINS=/usr/lib/python2.7/site-packages/ara/plugins/callbacks
+    export ANSIBLE_ACTION_PLUGINS=/usr/lib/python2.7/site-packages/ara/plugins/actions
+    export ANSIBLE_LIBRARY=/usr/lib/python2.7/site-packages/ara/plugins/modules
+
+Note that the module doesn't actually run those exports, you'll want to run them
+yourself, add them in a bash script or a bashrc, etc.
 
 .. _environment variables: https://docs.ansible.com/ansible/intro_configuration.html#environmental-configuration
 

doc/source/contributing.rst

@@ -166,8 +166,6 @@ Documentation tests::
 
 Integration tests:
 
-::
-
 At the root of the ARA source, you'll find the ``run_tests.sh`` script that
 allows you to easily run integration tests across a range of different
 configurations.

run_tests.sh

@@ -108,10 +108,18 @@ if [[ $ARA_TEST_PGSQL == 1 ]]; then
     pip install psycopg2
 fi
 
+# TODO: Improve the testing of those
+echo "python -m ara.setup.path: $(python -m ara.setup.path)"
+echo "python -m ara.setup.callback_plugins: $(python -m ara.setup.callback_plugins)"
+echo "python -m ara.setup.action_plugins: $(python -m ara.setup.action_plugins)"
+echo "python -m ara.setup.library: $(python -m ara.setup.library)"
+echo "python -m ara.setup.env: $(python -m ara.setup.env)"
+echo "python -m ara.setup.ansible: $(python -m ara.setup.ansible)"
+
 # Setup ARA
-export ANSIBLE_CALLBACK_PLUGINS="ara/plugins/callbacks"
-export ANSIBLE_ACTION_PLUGINS="ara/plugins/actions"
-export ANSIBLE_LIBRARY="ara/plugins/modules"
+export ANSIBLE_CALLBACK_PLUGINS="$(python -m ara.setup.callback_plugins)"
+export ANSIBLE_ACTION_PLUGINS="$(python -m ara.setup.action_plugins)"
+export ANSIBLE_LIBRARY="$(python -m ara.setup.library)"
 export ARA_DATABASE="${DATABASE}"
 
 # Run linters