diff --git a/.zuul.d/project.yaml b/.zuul.d/project.yaml index 3bce2a71..ae48d6cf 100644 --- a/.zuul.d/project.yaml +++ b/.zuul.d/project.yaml @@ -1,4 +1,8 @@ - project: + vars: + rtd_webhook_id: '49230' + templates: + - docs-on-readthedocs check: jobs: - ara-server-ansible-integration: diff --git a/doc/source/_graphs/README b/doc/source/_graphs/README new file mode 100644 index 00000000..a9c2e491 --- /dev/null +++ b/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. diff --git a/doc/source/_graphs/recording-workflow.xml b/doc/source/_graphs/recording-workflow.xml new file mode 100644 index 00000000..2a137597 --- /dev/null +++ b/doc/source/_graphs/recording-workflow.xml @@ -0,0 +1 @@ +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 \ No newline at end of file diff --git a/doc/source/_static/ara.png b/doc/source/_static/ara.png new file mode 100755 index 00000000..71b130fe Binary files /dev/null and b/doc/source/_static/ara.png differ diff --git a/doc/source/_static/graphs/README b/doc/source/_static/graphs/README new file mode 100644 index 00000000..dbaa4304 --- /dev/null +++ b/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``. diff --git a/doc/source/_static/graphs/recording-workflow.png b/doc/source/_static/graphs/recording-workflow.png new file mode 100644 index 00000000..0340cad0 Binary files /dev/null and b/doc/source/_static/graphs/recording-workflow.png differ diff --git a/doc/source/arch.rst b/doc/source/arch.rst new file mode 100644 index 00000000..965d7950 --- /dev/null +++ b/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 diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 00000000..b044934b --- /dev/null +++ b/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 . + +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} diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 00000000..acffc074 --- /dev/null +++ b/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