From c08788f39386363ebb8e606dfd95fcc8989fc0fc Mon Sep 17 00:00:00 2001 From: Simon Pasquier Date: Wed, 18 May 2016 10:38:23 +0200 Subject: [PATCH] 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 | 8 ++ doc/conf.py | 36 +++++++++ doc/elasticsearch_kibana.rst | 14 ++++ doc/index.rst | 11 +++ doc/influxdb_grafana.rst | 20 +++++ doc/lma_collector.rst | 8 ++ doc/lma_infrastructure_alerting.rst | 14 ++++ stacklight_tests/helpers/helpers.py | 2 +- .../influxdb_grafana/test_destructive.py | 1 + .../test_system.py | 36 ++++----- tox.ini | 13 +++- utils/fuel-qa-builder/prepare_env.sh | 78 ++++++++++--------- 12 files changed, 185 insertions(+), 56 deletions(-) create mode 100644 doc/conf.py create mode 100644 doc/elasticsearch_kibana.rst create mode 100644 doc/index.rst create mode 100644 doc/influxdb_grafana.rst create mode 100644 doc/lma_collector.rst create mode 100644 doc/lma_infrastructure_alerting.rst diff --git a/README.md b/README.md index f6399d3..7c8581d 100644 --- a/README.md +++ b/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= +## 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, diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..0bb0d35 --- /dev/null +++ b/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} diff --git a/doc/elasticsearch_kibana.rst b/doc/elasticsearch_kibana.rst new file mode 100644 index 0000000..c935d03 --- /dev/null +++ b/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: diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..9462444 --- /dev/null +++ b/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 diff --git a/doc/influxdb_grafana.rst b/doc/influxdb_grafana.rst new file mode 100644 index 0000000..aa7c64f --- /dev/null +++ b/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: diff --git a/doc/lma_collector.rst b/doc/lma_collector.rst new file mode 100644 index 0000000..1d455b3 --- /dev/null +++ b/doc/lma_collector.rst @@ -0,0 +1,8 @@ +LMA Collector Plugin +******************** + +Smoke/BVT +========= + +.. automodule:: stacklight_tests.lma_collector.test_smoke_bvt + :members: diff --git a/doc/lma_infrastructure_alerting.rst b/doc/lma_infrastructure_alerting.rst new file mode 100644 index 0000000..0c3838e --- /dev/null +++ b/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: diff --git a/stacklight_tests/helpers/helpers.py b/stacklight_tests/helpers/helpers.py index 360181e..6c7e859 100644 --- a/stacklight_tests/helpers/helpers.py +++ b/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: diff --git a/stacklight_tests/influxdb_grafana/test_destructive.py b/stacklight_tests/influxdb_grafana/test_destructive.py index 7207d37..a2672bd 100644 --- a/stacklight_tests/influxdb_grafana/test_destructive.py +++ b/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 """ diff --git a/stacklight_tests/lma_infrastructure_alerting/test_system.py b/stacklight_tests/lma_infrastructure_alerting/test_system.py index 26df351..5086696 100644 --- a/stacklight_tests/lma_infrastructure_alerting/test_system.py +++ b/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 """ diff --git a/tox.ini b/tox.ini index e76d97a..b823f2d 100644 --- a/tox.ini +++ b/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 diff --git a/utils/fuel-qa-builder/prepare_env.sh b/utils/fuel-qa-builder/prepare_env.sh index d954707..5ed28ce 100755 --- a/utils/fuel-qa-builder/prepare_env.sh +++ b/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"