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