Cleanup tempest docs a bit

This commit fixes a few things in the tempest docs. First it fixes all
of the sphinx warnings and enables fail on warn to ensure we're using
valid sphinx everywhere. It also adds a link from the configuration
guide to the sample config file.

Change-Id: I3ad645a6bbfa46b4498e1732410743e46d6eb0cb

HACKING.rst

@@ -72,11 +72,10 @@ for providing more information.
 Most other assert method can include more information by default.
 For example ``self.assertIn`` can include the whole set.
 
-It is recommended to use testtools matcher for the more tricky assertions.
-`[doc] <http://testtools.readthedocs.org/en/latest/for-test-authors.html#matchers>`_
+It is recommended to use testtools `matcher`_ for the more tricky assertions.
+You can implement your own specific `matcher`_ as well.
 
-You can implement your own specific matcher as well.
-`[doc] <http://testtools.readthedocs.org/en/latest/for-test-authors.html#writing-your-own-matchers>`_
+.. _matcher: http://testtools.readthedocs.org/en/latest/for-test-authors.html#matchers
 
 If the test case fails you can see the related logs and the information
 carried by the exception (exception class, backtrack and exception info).
@@ -158,8 +157,8 @@ is to create an interface description in a python file under
 sections for the test (one of those is mandatory):
 
  - A resource (part of the URL of the request): Resources needed for a test
- must be created in `setUpClass` and registered with `set_resource` e.g.:
- `cls.set_resource("server", server['id'])`
+   must be created in `setUpClass` and registered with `set_resource` e.g.:
+   `cls.set_resource("server", server['id'])`
 
  - A json schema: defines properties for a request.
 

README.rst

@@ -191,8 +191,6 @@ tests by using ``testr`` ::
 
     $> testr run --parallel
 
-.. _testr: http://testrepository.readthedocs.org/en/latest/MANUAL.html
-
 To run one single test serially ::
 
     $> testr run tempest.api.compute.servers.test_servers_negative.ServersNegativeTestJSON.test_reboot_non_existent_server

REVIEWING.rst

@@ -34,7 +34,7 @@ should not be approved.
 
 
 Reject Copy and Paste Test Code
-------------------------
+-------------------------------
 When creating new tests that are similar to existing tests it is tempting to
 simply copy the code and make a few modifications. This increases code size and
 the maintenance burden. Such changes should not be approved if it is easy to

doc/source/account_generator.rst

@@ -1,5 +1,5 @@
---------------------------------
+--------------------------------------
 Tempest Test-Account Generator Utility
---------------------------------
+--------------------------------------
 
-.. automodule:: tempest.cmd.account_generator
+.. automodule:: tempest.cmd.account_generator

doc/source/configuration.rst

@@ -6,7 +6,8 @@ Tempest Configuration Guide
 This guide is a starting point for configuring tempest. It aims to elaborate
 on and explain some of the mandatory and common configuration settings and how
 they are used in conjunction. The source of truth on each option is the sample
-config file which explains the purpose of each individual option.
+config file which explains the purpose of each individual option. You can see
+the sample config file here: :ref:`tempest-sampleconf`
 
 Lock Path
 ---------

doc/source/index.rst

@@ -24,7 +24,6 @@ where your test contributions should go.
 
    field_guide/index
    field_guide/api
-   field_guide/cli
    field_guide/scenario
    field_guide/stress
    field_guide/thirdparty

setup.cfg

@@ -42,5 +42,8 @@ all_files = 1
 build-dir = doc/build
 source-dir = doc/source
 
+[pbr]
+warnerrors = True
+
 [wheel]
 universal = 1

tempest/README.rst

@@ -57,7 +57,7 @@ several test jobs in parallel and can run any existing test in Tempest as a
 stress job.
 
 :ref:`third_party_field_guide`
------------------------------
+------------------------------
 
 Many openstack components include 3rdparty API support. It is
 completely legitimate for Tempest to include tests of 3rdparty APIs,

tempest/cmd/account_generator.py

@@ -25,7 +25,7 @@ have the username, tenant_name, password and roles.
 **Usage:** ``tempest-account-generator [-h] [OPTIONS] accounts_file.yaml``.
 
 Positional Arguments
------------------
+--------------------
 **accounts_file.yaml** (Required) Provide an output accounts yaml file. Utility
 creates a .yaml file in the directory where the command is ran. The appropriate
 name for the file is *accounts.yaml* and it should be placed in *tempest/etc*
@@ -49,7 +49,7 @@ You're probably familiar with these, but just to remind::
     +----------+------------------+----------------------+
 
 Optional Arguments
------------------
+------------------
 **-h**, **--help** (Optional) Shows help message with the description of
 utility and its arguments, and exits.