Update docs to points to readthedocs.io

Also add a YAML sample in README and front page of docs.

README.rst

@@ -1,15 +1,22 @@
 .. image:: https://travis-ci.org/cdent/gabbi.svg?branch=master
     :target: https://travis-ci.org/cdent/gabbi
 .. image:: https://readthedocs.org/projects/gabbi/badge/?version=latest
-    :target: https://gabbi.readthedocs.org/en/latest/
+    :target: https://gabbi.readthedocs.io/en/latest/
     :alt: Documentation Status
 
 Gabbi
 =====
 
 Gabbi is a tool for running HTTP tests where requests and responses
-are represented in a declarative YAML-based form. See the docs_ for
-more details on features and formats.
+are represented in a declarative YAML-based form. The simplest test
+looks like this::
+
+    tests:
+    - name: A test
+      GET: /api/resources/id
+
+See the docs_ for more details on the many features and formats for
+setting request headers and bodies and evaluating responses.
 
 Gabbi is tested with Python 2.7, 3.4, 3.5 and pypy.
 
@@ -20,12 +27,12 @@ There is a `gabbi-demo`_ repository which provides a tutorial via
 its commit history. The demo builds a simple API using gabbi to
 facilitate test driven development.
 
-.. _docs: https://gabbi.readthedocs.org/
+.. _docs: https://gabbi.readthedocs.io/
 .. _gabbi-demo: https://github.com/cdent/gabbi-demo
-.. _unittest: https://gabbi.readthedocs.org/en/latest/example.html#loader
+.. _unittest: https://gabbi.readthedocs.io/en/latest/example.html#loader
 .. _pytest: http://pytest.org/
-.. _loader docs: https://gabbi.readthedocs.org/en/latest/example.html#pytest
-.. _gabbi-run: https://gabbi.readthedocs.org/en/latest/runner.html
+.. _loader docs: https://gabbi.readthedocs.io/en/latest/example.html#pytest
+.. _gabbi-run: https://gabbi.readthedocs.io/en/latest/runner.html
 
 Purpose
 -------

docs/source/example.yaml

@@ -190,7 +190,7 @@ tests:
 # "$ENVIRON" is a pseudo dictionary providing access to the current
 # environment.
 # "$RESPONSE" provides access to the JSON in the prior response, via
-# JSONPath. See http://jsonpath-rw.readthedocs.org/en/latest/ for
+# JSONPath. See http://jsonpath-rw.readthedocs.io/ for
 # jsonpath-rw formatting.
 # $SCHEME and $NETLOC provide access to the current protocol and
 # location (host and port).

docs/source/index.rst

@@ -19,15 +19,24 @@
 Gabbi
 =====
 
+.. highlight:: yaml
+
 Gabbi is a tool for running HTTP tests where requests and responses
-are expressed as declarations in a collection of YAML files.
+are expressed as declarations in a collection of YAML files. The
+simplest test looks like this::
+
+    tests:
+    - name: A test
+      GET: /api/resources/id
+
+See the rest of these docs for more details on the many features and
+formats for setting request headers and bodies and evaluating responses.
 
 The name is derived from "gabby": excessively talkative. In a test
 environment having visibility of what a test is actually doing is a
-good thing. The "y" to an "i" is an optimization for as yet to be
-determined backronyms such as: "Garrulous API Barrier Breaking
-Initiative" or "Glorious And Basic Beta Investigator". These
-are not good enough so the search continues.
+good thing. This is especially true when the goal of a test is to
+test the HTTP, not the testing infrastructure. Gabbi tries to put
+the HTTP interaction in the foreground of testing.
 
 Tests can be run using :ref:`unittest <test_loaders>` style test
 runners or py.test or from the command line with a :doc:`gabbi-run <runner>` script.
@@ -43,6 +52,8 @@ of using gabbi to build an API, via the commit history of the repo.
 Purpose
 -------
 
+.. highlight:: none
+
 Gabbi works to bridge the gap between human readable YAML files (see
 :doc:`format` for details) that represent HTTP requests and expected
 responses and the rather complex world of automated testing.

docs/source/jsonpath.rst

@@ -67,5 +67,5 @@ not just your API interactions.
 There are more JSONPath examples in :doc:`example` and in the
 `jsonpath_rw`_ and `jsonpath_rw_ext`_ documentation.
 
-.. _jsonpath_rw: http://jsonpath-rw.readthedocs.org/en/latest/
-.. _jsonpath_rw_ext: https://python-jsonpath-rw-ext.readthedocs.org/en/latest/
+.. _jsonpath_rw: http://jsonpath-rw.readthedocs.io/en/latest/
+.. _jsonpath_rw_ext: https://python-jsonpath-rw-ext.readthedocs.io/en/latest/

gabbi/__init__.py

@@ -12,4 +12,4 @@
 # under the License.
 """See gabbi.driver and gabbbi.case."""
 
-__version__ = '1.17.4'
+__version__ = '1.17.5'