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

@@ -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.

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

doc/source/db_api.rst

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

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