Documentation Updates

Signed-off-by: Jason Myers <jason@jasonamyers.com>

.gitignore

@@ -10,3 +10,4 @@ AUTHORS
 ChangeLog
 # Generated by testrepository
 .testrepository
+.idea

docs/source/fixtures.rst

@@ -1,13 +1,13 @@
 Fixtures
 ========
 
-Each suite of tests represented by a single YAML file may optionally
-use one or more fixtures to provide the necessary environment for
-tests to run.
+Each suite of tests is represented by a single YAML file, and may
+optionally use one or more fixtures to provide the necessary
+environment for tests to run.
 
 Fixtures are implemented as nested context managers. Subclasses
 of :class:`~gabbi.fixture.GabbiFixture` must implement 
-``start_fixture`` and ``stop_fixture`` methods creating and
+``start_fixture`` and ``stop_fixture`` methods for creating and
 destroying, respectively, any resources managed by the fixture.
 While the subclass may choose to implement ``__init__`` it is
 important that no exceptions are thrown in that method, otherwise

docs/source/format.rst

@@ -1,7 +1,7 @@
 Test Format
 ===========
 
-Gabbi tests are expressed as YAML containing an HTTP request and an
+Gabbi tests are expressed in YAML containing an HTTP request and an
 expected response. Each YAML file is an ordered sequence of requests.
 The bare minimum YAML file for a single request is::
 
@@ -76,7 +76,7 @@ reference to the state of a current test or the one just prior. These
 are replaced with real values during test processing. They are
 processed in the order given.
 
-* ``$SCHEME``: The current scheme (usually ``http`` or ``https``).
+* ``$SCHEME``: The current scheme/protocol (usually ``http`` or ``https``).
 * ``$NETLOC``: The host and potentially port of the request.
 * ``$ENVIRON['<environment variable>']``: The name of an environment
   variable. It value will replace the magical variable.

docs/source/handlers.rst

@@ -2,7 +2,7 @@ Response Handlers
 =================
 
 Response handlers determine how an HTTP response will be processed and checked
-against the expected result. For each entry starting with `response_`, an
+against an expected result. For each entry starting with `response_`, an
 associated class is invoked with corresponding values. For example
 if the following lines are in a test::
 
@@ -10,7 +10,7 @@ if the following lines are in a test::
         - "lorem ipsum"
         - "dolor sit amet"
 
-this creates an instance of ``StringResponseHandler``, passing the value
+these lines create an instance of ``StringResponseHandler``, passing the value
 ``["lorem ipsum", "dolor sit amet"]``. The response handler
 implementation interprets the response and the expected values, determining
 whether the test passes or fails.

docs/source/host.rst

@@ -1,11 +1,9 @@
 Target Host
 ===========
 
-For the implementation of the following discussion see
-:meth:`~gabbi.driver.build_tests`.
-
+The target host is the host on which the API to be tested can be found.
 Gabbi intends to preserve the flow and semantics of HTTP interactions
-as much as possible. Every HTTP request needs to be directed at a host
+as much as possible, and every HTTP request needs to be directed at a host
 of some form. Gabbi provides three ways to control this:
 
 * Using `wsgi-intercept`_ to provide a fake socket and ``WSGI``
@@ -16,8 +14,8 @@ of some form. Gabbi provides three ways to control this:
 * Using a host and (optionally) port defined at test build time (see
   `live examples`_).
 
-Intercept and live are mutually exclusive per test builder, but either
-kind of test can freely intermix fully qualified URLs into the
+The intercept and live methods are mutually exclusive per test builder,
+but either kind of test can freely intermix fully qualified URLs into the
 sequence of tests in a YAML file.
 
 For test driven development and local tests the intercept style of
@@ -26,6 +24,8 @@ Interception is performed as part of :doc:`fixtures` processing as the most
 deeply nested fixture. This allows any configuration or database
 setup to be performed prior to the WSGI application being created.
 
+For the implementation of the above see :meth:`~gabbi.driver.build_tests`.
+
 .. _wsgi-intercept: https://pypi.python.org/pypi/wsgi_intercept
 .. _intercept examples: https://github.com/cdent/gabbi/blob/master/gabbi/test_intercept.py
 .. _full examples: https://github.com/cdent/gabbi/blob/master/gabbi/gabbits_intercept/google.yaml