Add some initial doc files

Still lots to fill in here, but it's better than nothing.

Makefile

@@ -6,6 +6,7 @@ clean:
 	rm -r dist || true
 	rm -r build || true
 	rm -r .tox || true
+	rm -r .eggs || true
 	rm -r gabbi.egg-info || true
 
 tagv:
@@ -19,6 +20,7 @@ cleanagain:
 	rm -r dist || true
 	rm -r build || true
 	rm -r .tox || true
+	rm -r .eggs || true
 	rm -r gabbi.egg-info || true
 
 test:

docs/source/conf.py

@@ -18,7 +18,8 @@ import os
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+docroot = os.path.abspath('../..')
+sys.path.insert(0, docroot)
 
 # -- General configuration ------------------------------------------------
 
@@ -31,7 +32,6 @@ import os
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.coverage',
-    'sphinx.ext.viewcode',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/fixtures.rst

@@ -0,0 +1,4 @@
+Fixtures
+========
+
+To be written. In the meantime see :class:`~gabbi.fixture.GabbiFixture`.

docs/source/format.rst

@@ -0,0 +1,25 @@
+Test Format
+===========
+
+Gabbi tests are expressed as 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:::
+
+    tests:
+       - name: the name of a test
+         url: /
+
+This will make a request to ``/`` on whatever the configured
+:doc:`host` is. The test will pass if the status of the HTTP response
+is ``200``.
+
+The ``tests`` key can contain as many requests, in sequence, as
+required. Other top level keys are:
+
+* fixtures: A sequence of named :doc:`fixtures`.
+* defaults: A dictionary of local default values for the requests and
+  responses in the ``tests`` in this file. These override the global
+  defaults (explained below).
+
+Each test can use the following structure. Only ``name`` and ``url``
+are required.

docs/source/gabbi.rst

@@ -0,0 +1,34 @@
+gabbi Package
+=================
+
+:mod:`case` Module
+------------------
+
+.. automodule:: gabbi.case
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`driver` Module
+--------------------
+
+.. automodule:: gabbi.driver
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`fixture` Module
+---------------------
+
+.. automodule:: gabbi.fixture
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`suite` Module
+-------------------
+
+.. automodule:: gabbi.suite
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/host.rst

@@ -0,0 +1,6 @@
+Target Host
+===========
+
+Information on how the concept of a host works. To be written. In the
+meantime see :meth:`~gabbi.driver.build_tests`.
+

docs/source/index.rst

@@ -3,20 +3,61 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Gabbi's documentation!
-=================================
-
-Contents:
-
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+   :hidden:
 
+   format
+   host
+   fixtures
+   gabbi
 
+Gabbi
+=====
 
-Indices and tables
-==================
+Gabbi is a tool for running HTTP tests where requests and responses
+are expressed as declarations in a collection of YAML files.
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+If you're not after the overview see the :doc:`gabbi` documentation
+and the test files in the `source distribution`_.
 
+.. _source distribution: https://github.com/cdent/gabbi
+
+Purpose
+-------
+
+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 obscured realm of Python-based, object-oriented unit
+tests in the style of the unittest module and its derivatives.
+
+Each YAML file represents an ordered list of HTTP requests along with
+the expected responses. This allows a single file to represent a
+process in the API being tested. For example:
+
+* Create a resource.
+* Retrieve a resource.
+* Delete a resource.
+* Retrieve a resource again to confirm it is gone.
+
+At the same time it is still possible to ask gabbi to run just one
+request. If it is in a sequence of tests, those tests prior to it in
+the YAML file will be run (in order). In any single process any test
+will only be run once. Concurrency is handled such that one file runs
+in one process.
+
+These features mean that it is possible to create tests that are useful
+for both humans (as tools for learning, improving and developing APIs)
+and automated CI systems.
+
+Extended functionality, such as the use of jsonpath to query response
+bodies and reuse the prior response data in the current request,
+exists to make it easier to test relatively complex JSON-driven APIs,
+even those bold enough to lay claim to being fully RESTful with
+HATEOAS.
+
+This functionality should not be taken as license to write gloriously
+complex test files. If your API is so complex that it needs complex
+test files then you may wish to take that as a sign that your API
+itself too complex. In many cases you may find it useful to write the
+test files first.

setup.cfg

@@ -27,5 +27,5 @@ packages =
 
 [build_sphinx]
 all_files = 1
-build-dir = doc/build
-source-dir = doc/source
+build-dir = docs/build
+source-dir = docs/source