Generate documentation automatically

This change adds a new tox target to generate the documentation from
the code. It also modifies the prepare_env.sh script so it doesn't try
to recreate everything when the virtual environment already exists.

Change-Id: Ia3ef1ec843ecfde83219cd6d5a3193b36bbf5371

README.md

@@ -28,6 +28,14 @@ for the detailed procedure).
 
         ./utils/jenkins/system_tests.sh -k -K -j fuelweb_test -t test -w $(pwd) -o --group=<your_test_group_to_run>
 
+## Documentation
+
+The test cases include comments that can be turned into human-readable documentation:
+
+        tox -edocs
+
+The generated documentation is available at `doc/_build/html/index.html`.
+
 ## Contributing
 
 If you would like to contribute to the development of this plugin,

doc/conf.py

@@ -0,0 +1,36 @@
+import os
+import sys
+
+sys.path.insert(0,
+                os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode',
+]
+
+autodoc_default_flags = ['members', 'show-inheritance', 'inherited-members']
+autodoc_member_order = 'bysource'
+
+source_suffix = '.rst'
+
+master_doc = 'index'
+
+project = 'StackLight Integration Tests'
+copyright = 'Copyright 2016 Mirantis, Inc.' \
+            'Licensed under the Apache License, Version 2.0' \
+            ' (the "License"); you may not use this file except in' \
+            ' compliance with the License. You may obtain a copy' \
+            ' of the License at http://www.apache.org/licenses/LICENSE-2.0'
+
+exclude_patterns = ['_build']
+
+pygments_style = 'sphinx'
+
+html_theme = 'default'
+htmlhelp_basename = 'StackLightintegrationtestsdoc'
+
+intersphinx_mapping = {'http://docs.python.org/': None}

doc/elasticsearch_kibana.rst

@@ -0,0 +1,14 @@
+Elasticsearch/Kibana Plugin
+***************************
+
+Smoke/BVT
+=========
+
+.. automodule:: stacklight_tests.elasticsearch_kibana.test_smoke_bvt
+   :members:
+
+System
+======
+
+.. automodule:: stacklight_tests.elasticsearch_kibana.test_system
+   :members:

doc/index.rst

@@ -0,0 +1,11 @@
+StackLight Integration Tests Documentation
+******************************************
+
+.. toctree::
+    :numbered:
+    :maxdepth: 3
+
+    elasticsearch_kibana.rst
+    influxdb_grafana.rst
+    lma_collector.rst
+    lma_infrastructure_alerting.rst

doc/influxdb_grafana.rst

@@ -0,0 +1,20 @@
+InfluxDB/Grafana Plugin
+***********************
+
+Smoke/BVT
+=========
+
+.. automodule:: stacklight_tests.influxdb_grafana.test_smoke_bvt
+   :members:
+
+System
+======
+
+.. automodule:: stacklight_tests.influxdb_grafana.test_system
+   :members:
+
+Destructive
+===========
+
+.. automodule:: stacklight_tests.influxdb_grafana.test_destructive
+   :members:

doc/lma_collector.rst

@@ -0,0 +1,8 @@
+LMA Collector Plugin
+********************
+
+Smoke/BVT
+=========
+
+.. automodule:: stacklight_tests.lma_collector.test_smoke_bvt
+   :members:

doc/lma_infrastructure_alerting.rst

@@ -0,0 +1,14 @@
+LMA Infrastructure Alerting Plugin
+**********************************
+
+Smoke/BVT
+=========
+
+.. automodule:: stacklight_tests.lma_infrastructure_alerting.test_smoke_bvt
+   :members:
+
+System
+======
+
+.. automodule:: stacklight_tests.lma_infrastructure_alerting.test_system
+   :members:

stacklight_tests/helpers/helpers.py

@@ -34,7 +34,7 @@ def get_plugin_version(filename):
     :returns: the plugin's version or None if not found
     :rtype: str
     """
-    m = PACKAGE_VERSION_RE.search(filename)
+    m = PACKAGE_VERSION_RE.search(filename or '')
     if m:
         return m.group(1)
     else:

stacklight_tests/influxdb_grafana/test_destructive.py

@@ -68,6 +68,7 @@ class TestDestructiveInfluxdbPlugin(api.InfluxdbPluginApi):
             3. Wait for at least 30 seconds before recover network availability
             5. Run OSTF
             6. Check that plugin is working
+
         Duration 20m
         Snapshot check_node_outage_influxdb_grafana
         """

stacklight_tests/lma_infrastructure_alerting/test_system.py

@@ -37,7 +37,7 @@ class TestLMAInfraAlertingPluginSystem(api.InfraAlertingPluginApi):
             2.  Re-deploy the cluster.
             3.  Check the plugin services using the CLI
             4.  Check in the Nagios UI that the removed node is no
-            longer monitored.
+                longer monitored.
             5.  Run the health checks (OSTF).
             6.  Add 1 new node with the controller role.
             7.  Re-deploy the cluster.
@@ -73,7 +73,7 @@ class TestLMAInfraAlertingPluginSystem(api.InfraAlertingPluginApi):
             2.  Re-deploy the cluster.
             3.  Check the plugin services using the CLI
             4.  Check in the Nagios UI that the removed node is no
-             longer monitored.
+                longer monitored.
             5.  Run the health checks (OSTF).
             6.  Add 1 new node with the compute role.
             7.  Re-deploy the cluster.
@@ -147,15 +147,15 @@ class TestLMAInfraAlertingPluginSystem(api.InfraAlertingPluginApi):
         """Shutdown infrastructure alerting node
 
         Scenario:
-            1.  Connect to any infrastructure_alerting node and run
-             command ‘crm status’.
-            2.  Shutdown node were vip_infrastructure_alerting_mgmt_vip
-             was started.
-            3.  Check that vip_infrastructure_alerting was started
-             on another infrastructure_alerting node.
-            4.  Check that Nagios UI works correctly.
-            5.  Check that no data lost after shutdown.
-            6.  Run OSTF.
+            1. Connect to any infrastructure_alerting node and run
+               command 'crm status'.
+            2. Shutdown node were vip_infrastructure_alerting_mgmt_vip
+               was started.
+            3. Check that vip_infrastructure_alerting was started
+               on another infrastructure_alerting node.
+            4. Check that Nagios UI works correctly.
+            5. Check that no data lost after shutdown.
+            6. Run OSTF.
 
         Duration 60m
         """
@@ -177,13 +177,13 @@ class TestLMAInfraAlertingPluginSystem(api.InfraAlertingPluginApi):
         """Run fuel-createmirror and deploy environment
 
         Scenario:
-            1.  Copy the plugins to the Fuel Master node and
-             install the plugins.
-            2.  Run the following command on the master node:
-                    fuel-createmirror
-            3.  Create an environment with enabled plugins in the
-            Fuel Web UI and deploy it.
-            4.  Run OSTF.
+            1. Copy the plugins to the Fuel Master node and
+               install the plugins.
+            2. Run the following command on the master node:
+               fuel-createmirror
+            3. Create an environment with enabled plugins in the
+               Fuel Web UI and deploy it.
+            4. Run OSTF.
 
         Duration 60m
         """

tox.ini

@@ -1,7 +1,7 @@
 [tox]
 minversion = 1.6
 skipsdist = True
-envlist = pep8
+envlist = pep8,docs
 
 [testenv:pep8]
 deps = hacking
@@ -14,3 +14,14 @@ ignore = H405, H703
 show-source = true
 exclude = .venv,.git,.tox,dist,doc,*egg,*lib/python*,build,releasenotes,tmp,utils/fuel-qa-builder/venv*
 max-complexity=25
+
+[testenv:docs]
+changedir = doc
+setenv=
+    VENV_PATH={envdir}
+deps =
+    -r{toxinidir}/requirements.txt
+    sphinx
+commands =
+    {toxinidir}/utils/fuel-qa-builder/prepare_env.sh
+    sphinx-build -b html -d _build/doctrees . _build/html

utils/fuel-qa-builder/prepare_env.sh

@@ -1,54 +1,60 @@
 #!/bin/bash
 #
-# Script to setup a Python virtual environment with all the dependencies
-# installed
+# Script to setup a Python virtual environment (if needed) and install all the
+# project's dependencies
 
 set -e
 
-# Initialize variables
+# Initialize the variables
 BASE_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 VENV_PATH=${VENV_PATH:-"${BASE_DIR}"/venv-stacklight-tests}
 FUELQA_GITREF=${FUELQA_GITREF:-stable/8.0}
-VIRTUALENV_BINARY=$(which virtualenv)
 
-if [[ -z "${VIRTUALENV_BINARY}" ]]; then
-    echo 'Cannot find the virtualenv executable!'
-    echo 'You should install it either using pip or you distribution package manager.'
-    exit 1
+# Create the virtual environment if it doesn't exist yet
+if [[ ! -f "$VENV_PATH"/bin/activate ]]; then
+    if ! which virtualenv; then
+        echo 'Cannot find the virtualenv executable!'
+        echo 'You should install it either using pip or your distribution package manager.'
+        exit 1
+    fi
+
+    echo "Creating virtual environment in '$VENV_PATH'"
+    virtualenv "$VENV_PATH"
+    . "$VENV_PATH"/bin/activate
+
+    # Always upgrade to the latest version of pip
+    pip install -U pip
+else
+    . "$VENV_PATH"/bin/activate
 fi
 
-if [ ! -x "$VENV_PATH"/bin/activate ]; then
-    "$VIRTUALENV_BINARY" "$VENV_PATH"
+echo "Using virtual environment at '$VIRTUAL_ENV'"
+
+if [[ "$(pip show fuelweb-test)" == "" ]]; then
+    # Install fuel-qa in the virtual environment
+    FUELQA_GITREF=${FUELQA_GITREF:-stable/8.0}
+    echo "Checking out fuel-qa, reference: $FUELQA_GITREF"
+    FUELQA_DIR=$(mktemp -d)
+    git clone https://github.com/openstack/fuel-qa.git -- "$FUELQA_DIR"
+
+    pushd "$FUELQA_DIR"
+    git checkout "$FUELQA_GITREF"
+
+    cp "${BASE_DIR}"/{MANIFEST.in,setup.py} ./
+
+    python setup.py sdist
+    pip install dist/fuelweb_test*.tar.gz
+
+    # Clean up stuff
+    popd
+    rm -rf "$FUELQA_DIR"
 fi
 
-. "$VENV_PATH"/bin/activate
-
-# Always upgrade to the latest version of pip
-pip install -U pip
-
-# Install fuel-qa in the virtual environment
-FUELQA_GITREF=${FUELQA_GITREF:-stable/8.0}
-echo "Checking out fuel-qa/$FUELQA_GITREF"
-FUELQA_DIR=$(mktemp -d)
-git clone https://github.com/openstack/fuel-qa.git -- "$FUELQA_DIR"
-
-pushd "$FUELQA_DIR"
-git checkout "$FUELQA_GITREF"
-
-cp "${BASE_DIR}"/{MANIFEST.in,setup.py} ./
-
-python setup.py sdist
-pip install dist/fuelweb_test*.tar.gz
-
-# Clean up stuff
-popd
-rm -rf "$FUELQA_DIR"
-
-# Install project's dependencies
-pip install -rrequirements.txt
+# Install the project's dependencies
+pip install -r"${BASE_DIR}/../../requirements.txt"
 
 echo
 echo
 echo "The setup is now complete."
 echo "Run this command in your shell to activate your Python virtual environment:"
-echo "  . $VENV_PATH/bin/activate"
+echo "  . $VIRTUAL_ENV/bin/activate"