Merge "Update README" into feature/1.0

README.rst

@@ -1,122 +1,75 @@
 ARA Records Ansible
 ===================
 
+ARA Records Ansible playbooks and makes them easier to understand and troubleshoot.
+
 .. image:: doc/source/_static/ara-with-icon.png
 
-ARA Records Ansible playbook runs and makes the recorded data available and
+ARA saves playbook results to a local or remote database by using an Ansible
-intuitive for users and systems.
+callback plugin and provides an API to integrate this data in tools and interfaces.
 
-The project provides several distinct components in order to make this happen:
+This project provides the ARA API as well as the Ansible components.
 
-- An API server for sending and querying data relative to playbook execution results
+For the web client interface, see `ara-web <https://github.com/ansible-community/ara-web>`_.
-- An API client library for communicating with the API
-- An Ansible callback plugin to record events as they happen throughout the execution
-- An Ansible action module to associate arbitrary key/values to your playbook reports
 
 Quickstart
 ==========
 
-Here's how you can get started from scratch with default settings:
+Here's how you can get started from scratch with sane defaults:
 
 .. code-block:: bash
 
-    # Create a virtual environment and activate it so we don't conflict
+    # Create a python3 virtual environment and activate it so we don't conflict
     # with system or distribution packages
     python3 -m venv ~/.ara/virtualenv
     source ~/.ara/virtualenv/bin/activate
 
     # Install Ansible, ARA and it's API server dependencies
-    pip install ansible git+https://github.com/ansible-community/ara@feature/1.0[server]
+    pip install ansible ara[server]
 
     # Tell Ansible to use the ARA callback plugin
     export ANSIBLE_CALLBACK_PLUGINS="$(python -m ara.setup.callback_plugins)"
 
-    # Run your playbook as your normally would
+    # Run your playbook as usual
     ansible-playbook playbook.yml
 
-The data will be saved in real time throughout the execution of the Ansible playbook.
+If nothing went wrong, your playbook data should have been saved in a local
+database at ``~/.ara/server/ansible.sqlite``.
 
-What happens behind the scenes is that the ARA Ansible callback plugin used
+You can browse this data through the API by executing ``ara-manage runserver``
-the built-in API client to send the data to the API which then saved it to a
+and pointing your browser at http://127.0.0.1:8000/.
-database located by default at ``~/.ara/server/ansible.sqlite``.
 
-You're now ready to start poking at the API with the built-in
+That's it !
-`API clients <https://ara.readthedocs.io/en/feature-1.0/api-usage.html>`_ !
 
-If you'd like to have the ARA web reporting interface, take a look at
+Live demos
-`ara-web <https://github.com/ansible-community/ara-web>`_.
+==========
+
+You can find live demos deployed by the built-in ara_api_ and ara_web_ Ansible
+roles at https://api.demo.recordsansible.org and https://web.demo.recordsansible.org.
+
+.. _ara_api: https://ara.readthedocs.io/en/feature-1.0/ansible-role-ara-api.html
+.. _ara_web: https://ara.readthedocs.io/en/feature-1.0/ansible-role-ara-web.html
 
 Documentation
 =============
 
-Documentation for installing, configuring, running and using ara is
+Documentation for installing, configuring, running and using ARA is
 available on `readthedocs.io <https://ara.readthedocs.io/en/feature-1.0/>`_.
 
 Community and getting help
 ==========================
 
-You can chat with the ARA community on Slack and IRC.
+- Bugs, issues and enhancements: https://github.com/ansible-community/ara/issues
-The two are transparently bridged with teamchat_ which broadcasts messages from
+- IRC: #ara on `Freenode <https://webchat.freenode.net/?channels=#ara>`_
-one platform to the other.
+- Slack: https://arecordsansible.slack.com (`invitation link <https://join.slack.com/t/arecordsansible/shared_invite/enQtMjMxNzI4ODAxMDQxLWU4MmZhZTI4ZjRjOTUwZTM2MzM3MzcwNDU1YzFmNzRlMzI0NTUzNDY1MWJlNThhM2I4ZTViZjUwZTRkNTBiM2I>`_)
 
-In addition, you can also find ARA on Twitter: `@ARecordsAnsible <https://twitter.com/ARecordsAnsible>`_
+- Website and blog: https://ara.recordsansible.org
-
+- Twitter: https://twitter.com/arecordsansible
-**IRC**
-
-- Server: `irc.freenode.net`_
-- Channel: #ara
-
-**Slack**
-
-- https://arecordsansible.slack.com
-- Join with the `Slack invitation <https://join.slack.com/t/arecordsansible/shared_invite/enQtMjMxNzI4ODAxMDQxLWU4MmZhZTI4ZjRjOTUwZTM2MzM3MzcwNDU1YzFmNzRlMzI0NTUzNDY1MWJlNThhM2I4ZTViZjUwZTRkNTBiM2I>`_
-
-.. _teamchat: https://github.com/dmsimard/teamchat
-.. _irc.freenode.net: https://webchat.freenode.net/
-
-Development and testing
-=======================
-
-.. code-block:: bash
-
-  # Retrieve the source and check out the 1.0 branch
-  git clone https://github.com/ansible-community/ara
-  cd ara
-  git checkout feature/1.0
-
-  # Install tox from pip or from your distro packages
-  pip install tox
-
-  # Run Ansible integration tests with the latest version of Ansible
-  tox -e ansible-integration
-
-  # Run integration tests with a specific version of Ansible
-  # Note: tox will always use the latest version of Ansible to run the playbook which runs the tests.
-  # For example, if the latest version of Ansible is 2.7.9, it will use Ansible 2.7.9
-  # to install Ansible==2.6.15 in a virtual environment and 2.6.15 is what will be tested.
-  tox -e ansible-integration -- -e ara_tests_ansible_version=2.6.15
-
-  # Run integration tests with Ansible from source
-  tox -e ansible-integration -- -e "ara_tests_ansible_name=git+https://github.com/ansible/ansible"
-
-  # Run unit tests
-  tox -e py3
-
-  # Run linters (pep8, black, isort)
-  tox -e linters
-
-  # Run test server -> http://127.0.0.1:8000/api/v1/
-  tox -e runserver
-
-  # Build docs
-  tox -e docs
 
 Contributors
 ============
 
-See contributors on GitHub_.
+See contributors on `GitHub <https://github.com/ansible-community/ara/graphs/contributors>`_.
-
-.. _GitHub: https://github.com/ansible-community/ara/graphs/contributors
 
 Copyright
 =========