From 207964729bec3f6708be59dfb13f111030bb7b85 Mon Sep 17 00:00:00 2001 From: Chris Dent Date: Wed, 31 Dec 2014 21:42:50 +0000 Subject: [PATCH] Add some initial doc files Still lots to fill in here, but it's better than nothing. --- Makefile | 2 ++ docs/source/conf.py | 4 +-- docs/source/fixtures.rst | 4 +++ docs/source/format.rst | 25 ++++++++++++++++ docs/source/gabbi.rst | 34 ++++++++++++++++++++++ docs/source/host.rst | 6 ++++ docs/source/index.rst | 63 +++++++++++++++++++++++++++++++++------- setup.cfg | 4 +-- 8 files changed, 127 insertions(+), 15 deletions(-) create mode 100644 docs/source/fixtures.rst create mode 100644 docs/source/format.rst create mode 100644 docs/source/gabbi.rst create mode 100644 docs/source/host.rst diff --git a/Makefile b/Makefile index ed71e15..7a1c7b8 100644 --- a/Makefile +++ b/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: diff --git a/docs/source/conf.py b/docs/source/conf.py index 9e5ccd2..c070248 100644 --- a/docs/source/conf.py +++ b/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. diff --git a/docs/source/fixtures.rst b/docs/source/fixtures.rst new file mode 100644 index 0000000..1ff9db7 --- /dev/null +++ b/docs/source/fixtures.rst @@ -0,0 +1,4 @@ +Fixtures +======== + +To be written. In the meantime see :class:`~gabbi.fixture.GabbiFixture`. diff --git a/docs/source/format.rst b/docs/source/format.rst new file mode 100644 index 0000000..25fa327 --- /dev/null +++ b/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. diff --git a/docs/source/gabbi.rst b/docs/source/gabbi.rst new file mode 100644 index 0000000..c3f7ee1 --- /dev/null +++ b/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: diff --git a/docs/source/host.rst b/docs/source/host.rst new file mode 100644 index 0000000..314cfe7 --- /dev/null +++ b/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`. + diff --git a/docs/source/index.rst b/docs/source/index.rst index 3bc12b0..e1fa285 100644 --- a/docs/source/index.rst +++ b/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. diff --git a/setup.cfg b/setup.cfg index ee7d977..bc48de0 100644 --- a/setup.cfg +++ b/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