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
This commit is contained in:
Matthew Treinish 2014-07-27 13:06:34 -04:00
parent 10e5d0eda5
commit a08a7afa81
4 changed files with 63 additions and 0 deletions

View File

@ -1,3 +1,4 @@
==================
subunit2SQL README 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. 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 Additionally, it provides a DB API that can be used to query information from
the results stored to build other tooling. 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.

View File

@ -17,6 +17,7 @@ extensions = ['sphinx.ext.autodoc',
'sphinx.ext.intersphinx', 'sphinx.ext.intersphinx',
'sphinx.ext.todo', 'sphinx.ext.todo',
'sphinx.ext.viewcode', 'sphinx.ext.viewcode',
'oslosphinx'
] ]
todo_include_todos = True todo_include_todos = True

View File

@ -3,3 +3,7 @@ The DB API
---------- ----------
.. automodule:: subunit2sql.db.api .. automodule:: subunit2sql.db.api
:noindex:
:members:
:undoc-members:
:show-inheritance:

View File

@ -6,3 +6,4 @@ mock>=1.0
sphinx>=1.1.2,<1.2 sphinx>=1.1.2,<1.2
testrepository>=0.0.18 testrepository>=0.0.18
testtools>=0.9.34 testtools>=0.9.34
oslosphinx