Bootstrap documentation and publish it to readthedocs

Add a first bit of documentation around the workflow for recording data.

Change-Id: I9456b71c94e9097ea93394f8f7c33cd272586cc5

.zuul.d/project.yaml

@@ -1,4 +1,8 @@
 - project:
+    vars:
+      rtd_webhook_id: '49230'
+    templates:
+      - docs-on-readthedocs
     check:
       jobs:
         - ara-server-ansible-integration:

doc/source/_graphs/README

@@ -0,0 +1,7 @@
+graph source files
+==================
+
+These are exports from the ARA diagrams and graphs made through draw.io.
+
+We're keeping them for version control purposes but the documentation uses
+actual images built from these from the ``doc/source/_static/graphs`` directory.

doc/source/_graphs/recording-workflow.xml

@@ -0,0 +1 @@
+<mxfile userAgent="Mozilla/5.0 (X11; Fedora; Linux x86_64; rv:62.0) Gecko/20100101 Firefox/62.0" version="9.1.8" editor="www.draw.io" type="device"><diagram id="9906a0a6-bcd4-fe14-221d-85032a32ce87" name="Page-1">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</diagram></mxfile>

doc/source/_static/graphs/README

@@ -0,0 +1,7 @@
+graph image files
+=================
+
+These are image files for the ARA diagrams and graphs made through draw.io.
+
+The source files used to generate these graphs are located in
+``doc/source/_graphs``.

doc/source/arch.rst

@@ -0,0 +1,23 @@
+Architecture and Workflows
+==========================
+
+Recording data from Ansible
+---------------------------
+
+.. image:: _static/graphs/recording-workflow.png
+
+0. A human (*or a system, script, etc.*) installs ARA and configures Ansible to use the ARA callback
+1. A human (*or a system, script, etc.*) executes an ``ansible-playbook`` command
+2. Ansible sends hooks for every event to `callback plugins`_ (``v2_playbook_on_start``, ``v2_runner_on_failed``, etc.)
+3. The callback plugin, provided by ara-plugins_, organizes the data sent by Ansible and sends it to the API client
+4. The API client, provided by ara-clients_, takes care of actually sending the data to the API over HTTP or locally offline through an internal implementation
+5. The API server, provided by ara-server_, receives the POST from the client, validates it and sends it to the database model backend
+6. The API server sends a response back to the client with the results
+7. The API client sends the response back to the callback with the results
+8. The callback plugin returns, ending the callback hook
+9. Ansible continues running until it is complete (back to step 2)
+
+.. _callback plugins: https://docs.ansible.com/ansible/latest/plugins/callback.html
+.. _ara-plugins: https://github.com/openstack/ara-plugins
+.. _ara-clients: https://github.com/openstack/ara-clients
+.. _ara-server: https://github.com/openstack/ara-server

doc/source/conf.py

@@ -0,0 +1,86 @@
+# -*- coding: utf-8 -*-
+#  Copyright (c) 2018 Red Hat, Inc.
+#
+#  This file is part of ARA Records Ansible.
+#
+#  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
+import sys
+import sphinx_rtd_theme
+import pbr.version
+version_info = pbr.version.VersionInfo('ara-server')
+
+sys.path.insert(0, os.path.abspath('../..'))
+# -- General configuration ----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = [
+    'sphinx.ext.autodoc',
+]
+
+# autodoc generation is a bit aggressive and a nuisance when doing heavy
+# text edit cycles.
+# execute "export SPHINX_DEBUG=1" in your terminal to disable
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'ara-server'
+copyright = u'2018, Red Hat'
+author = 'OpenStack community'
+
+# The short X.Y version.
+version = version_info.version_string()
+# The full version, including alpha/beta/rc tags.
+release = version_info.release_string()
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for HTML output --------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+html_theme = 'sphinx_rtd_theme'
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_static_path = ['_static']
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = '%sdoc' % project
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass
+# [howto/manual]).
+latex_documents = [
+    ('index',
+     '%s.tex' % project,
+     u'%s Documentation' % project,
+     u'Red Hat', 'manual'),
+]
+
+# Example configuration for intersphinx: refer to the Python standard library.
+#intersphinx_mapping = {'http://docs.python.org/': None}

doc/source/index.rst

@@ -0,0 +1,11 @@
+Welcome to the ARA server documentation!
+========================================
+.. image:: _static/ara.png
+
+Table of Contents
+=================
+
+.. toctree::
+    :maxdepth: 3
+
+    Architecture and workflows <arch>