From a08a7afa81626847f60d62cbb602898d71796ead Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Sun, 27 Jul 2014 13:06:34 -0400 Subject: [PATCH] Update the documentation This commit updates the documentation for subunit2sql. It adds details to the README around running setting up the DB and running subunit2sql. Also, the db api autodoc usage is corrected so that it properly generates the documentation. Finally, the sphinx theme is switched to oslosphinx to have consistent style with the documentation for the other OpenStack projects. Related-Bug: #1348202 Change-Id: Icf148dee19bb888b551e60a396f87f6c09553e09 --- README.rst | 57 +++++++++++++++++++++++++++++++++++++++++++ doc/source/conf.py | 1 + doc/source/db_api.rst | 4 +++ test-requirements.txt | 1 + 4 files changed, 63 insertions(+) diff --git a/README.rst b/README.rst index 1618089..c2771e6 100644 --- a/README.rst +++ b/README.rst @@ -1,3 +1,4 @@ +================== subunit2SQL README ================== @@ -18,3 +19,59 @@ subunit2SQL uses alembic migrations to setup a DB schema that can then be used by the subunit2sql binary to parse subunit streams and populate the DB. Additionally, it provides a DB API that can be used to query information from the results stored to build other tooling. + +Usage +===== + +DB Setup +-------- + +The usage of subunit2ql is split into 2 stages. First you need to prepare a +database with the proper schema; alembic should be used to do this. The +alembic.ini file in-tree includes the necessary options for alembic, however +the database uri must be specificed with the option:: + + sqlalchemy.url = smysql:///user:pass@127.0.0.1/subunit + +to be able to use alembic to setup the db schema. Obviously the sql connector +type, user, password, address, and database name should be specific to your +environment. After the alembic.ini file is updated you perform can run the db +migrations with the command:: + + alembic upgrade head + +from the root path for subunit2sql. This will bring the DB schema up to the +latest version for subunit2sql. Also, it is worh noting that the schema +migrations used in subunit2sql do not currently support sqlite. While it is +possible to fix this, sqlite only supports a subset of the necessary sql calls +used by the migration scripts. As such, maintaining support for sqlite will be +a continual extra effort, so if support is added in the future, it is no +guarantee that it will remain. In addition, the performance of running, even in +a testing capacity, subunit2sql with MySQL or Postgres make it worth the effort +of setting up one of them to use subunit2sql. + +Running subunit2sql +------------------- + +Once you have a database setup with the proper database schema you can then use +the subunit2sql command to populate the database with data from your test runs. +subunit2sql takes in a subunit v2 either through stdin or by passing it file +paths as positional arguments to the script. If only a subunit v1 stream is +available, it can be converted to a subunit v2 stream using the subunit-1to2 +utility. + +There are several options for running subunit2sql, they can be listed with:: + + subunit2sql --help + +The only required options are the state_path and the database-connections. +These options and the other can either be used on the CLI, or put in a config +file. If a config file is used you need to specify the location on the CLI. + +Most of the optional arguments deal with how subunit2sql interacts with the +SQL DB. However, it is worth pointing out that the artifacts option and the +run_meta option are used to pass additional metadata into the database for the +run(s) being added. The artifacts option should be used to pass in a url or +path that points to any logs or other external test artifacts related to the +run being added. The run_meta option takes in a dictionary which will be added +to the database as key value pairs associated with the run being added. diff --git a/doc/source/conf.py b/doc/source/conf.py index 0bbc1a0..a215c8b 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -17,6 +17,7 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.viewcode', + 'oslosphinx' ] todo_include_todos = True diff --git a/doc/source/db_api.rst b/doc/source/db_api.rst index b6655c7..bf11f95 100644 --- a/doc/source/db_api.rst +++ b/doc/source/db_api.rst @@ -3,3 +3,7 @@ The DB API ---------- .. automodule:: subunit2sql.db.api + :noindex: + :members: + :undoc-members: + :show-inheritance: diff --git a/test-requirements.txt b/test-requirements.txt index 573e505..32eecea 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -6,3 +6,4 @@ mock>=1.0 sphinx>=1.1.2,<1.2 testrepository>=0.0.18 testtools>=0.9.34 +oslosphinx