Fix documentation before the release

A collection of doc fixes put together after documentation
testing, to make sure we have up-to-date docs before we
release.

Change-Id: Ia007a8a935a3c564f8b5c249293956e098da356b

doc/source/api.rst

@@ -74,6 +74,7 @@ db.::
 
     subunit_file = open('subunit_file', 'r')
     # Load default config
+    shell.cli_opts()
     shell.parse_args([])
     # Set database connection
     db_uri = 'mysql://subunit:subunit@localhost/subunit'
@@ -99,7 +100,7 @@ like::
     db_uri = 'mysql://subunit:subunit@localhost/subunit'
     shell.CONF.set_override('connection', db_uri, group='database')
     # Set run metadata and artifact path
-    aritfacts = 'http://fake_url.com'
+    artifacts = 'http://fake_url.com'
     metadata = {
         'job_type': 'full-run',
         'job_queue': 'gate',

doc/source/data_model.rst

@@ -13,6 +13,7 @@ high level information about them
 
 Properties:
 
+* **uuid**: A unique human-readable identifier for the run.
 * **passes**: The total number of successful tests in the run.
 * **fails**: The total number of failed tests during the run.
 * **skips**: The total number of skipped tests during the run.
@@ -35,7 +36,6 @@ stored in the db.
 
 Properties:
 
-* **id**: Database uuid of the row
 * **test_id**: This would be normally be considered the test name, it is the id
   used in the subunit stream for an individual test
 * **success**: The total number of times this test has been run successfully
@@ -54,9 +54,12 @@ used for recording all the information about a single test's run.
 
 Properties:
 
-* **test_id**: The uuid representing the test which was run. This correlates
+* **test_id**: The id representing the test which was run. This correlates
-               to the id column of the Tests table (And not the test_id column).
+               to the internal id column of the Tests table (And not the
-* **run_id**: The uuid representing the run this was part of
+               test_id column).
+* **run_id**: The id representing the run which this was part of. This
+              correlates to the internal id column of the Runs table (And not
+              the uuid column).
 * **status**: The outcome of the test. The valid values here are:
   exists, xfail, unxsuccess, success, fail, skip. You can refer to
   the `testtools documentation <http://testtools.readthedocs.org/en/latest/api.html#testtools.StreamResult.status>`_
@@ -75,7 +78,8 @@ particular test_run.
 
 Properties:
 
-* **test_run_id**: The uuid representing the test_run the attachment is
+* **test_run_id**: The id representing the test_run the attachment is
-                   associated with.
+                   associated with. This correlates to the internal id column
+                   of the the TestRuns table.
 * **label**: The label for the attachment
 * **attachment**: The actual attachment

doc/source/graph.rst

@@ -20,6 +20,11 @@ or::
 
     pip install $PATH_TO_subuni2sql[graph]
 
+For example::
+
+   git clone https://git.openstack.org/openstack-infra/subunit2sql .
+   pip install -e .[graph]
+
 
 Using subunit2sql-graph
 -----------------------
@@ -46,7 +51,7 @@ graph specific args must come after the graph on the CLI and general args must
 come before. This will likely change in the future, but at least for right now
 it's an existing issue.
 
-There are currently 3 graphs that it can generate:
+There are currently 4 graphs that it can generate:
 
 Run Time
 --------
@@ -56,7 +61,7 @@ specified test from the test_runs table.
 
 For example running something like::
 
-  subunit2sql-graph --database-connection mysql://test:test@localhost/subunit2sql --output test.png --title 'Test Run Times' run_time 0291fc87-1a6d-4c6b-91d2-00a7bb5c63e6
+  subunit2sql-graph --database-connection mysql://test:test@localhost/subunit2sql --output test.png --title 'Test Run Times' run_time tempest.api.identity.admin.v2.test_users.UsersTestJSON.test_update_user_password
 
 will generate a graph like:
 
@@ -77,7 +82,7 @@ for each of these counts (grouped daily) as different line plots on the same gra
 
 For example running something like::
 
-  subunit2sql-graph --database-connection mysql://test:test@localhost/subunit2sql --output test.png --title 'Test Failure Count' failures 0291fc87-1a6d-4c6b-91d2-00a7bb5c63e6
+  subunit2sql-graph --database-connection mysql://test:test@localhost/subunit2sql --output test.png --title 'Test Failure Count' failures tempest.api.compute.servers.test_server_actions.ServerActionsTestJSON.test_rebuild_server
 
 will generate a graph like: