Merge lp:~blr/rutabaga/doc-update into lp:rutabaga

[Kit Randel]

This branch splits Rutabaga's docs into 'Getting Started' and 'API documentation' sections. Currently Cornice API docs will render weirdly unfortunately (displaying str.__doc__), however I have provided a pull request on github to fix the issue (https://github.com/mozilla-services/cornice/pull/341).

A few trivial changes as well:

* Removed docstring references to lp specific infrastructure (builders).
* Added iso8601 dep to test-requirements.

[Colin Watson (cjwatson)]

review: Approve

[lp:~blr/rutabaga/doc-update]

45. By Kit Randel on 2015-11-19

Trivial grammar.

46. By Kit Randel on 2015-11-19

Merge devel.

=== added file 'docs/api.rst'
--- docs/api.rst	1970-01-01 00:00:00 +0000
+++ docs/api.rst	2015-11-19 21:45:01 +0000
@@ -0,0 +1,22 @@
+.. _api:
+
+API Documentation
+=================
+
+Web Token REST API
+##################
+
+The Rutabaga API provides the following endpoints:
+
+.. cornice-autodoc::
+   :modules: rutabaga.views
+          
+
+Auth API
+########
+
+The auth module provides methods for creating, persisting, invaliding
+and deleting tokens. Tokens are persisted to a sqlite3 store.
+
+.. automodule:: rutabaga.auth
+   :members:             

=== modified file 'docs/conf.py'
--- docs/conf.py	2015-07-24 05:33:16 +0000
+++ docs/conf.py	2015-11-19 21:45:01 +0000
@@ -100,7 +100,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'alabaster'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

=== added file 'docs/getting_started.rst'
--- docs/getting_started.rst	1970-01-01 00:00:00 +0000
+++ docs/getting_started.rst	2015-11-19 21:45:01 +0000
@@ -0,0 +1,40 @@
+.. _getting_started:
+
+Getting Started
+===============
+
+Get the source
+##############
+
+Rutabaga's source is available from `launchpad <https://launchpad.net/rutabaga>`_::
+
+    $ bzr branch lp:rutabaga
+
+Install Dependencies
+####################
+
+Ideally in a python3 virtualenv::
+
+    $ pip install -r requirements.txt
+    $ pip install -r test-requirements.txt
+
+
+Common Tasks
+############
+
+Create a new sqlite3 database::
+  
+    $ make schema
+
+Starting the dev server::
+
+    $ python3 setup.py develop
+    $ make start-api
+
+Running tests::
+
+    $ make
+
+The default make target (check) will run all of Rutabaga's tests.
+
+* :ref:`genindex`

=== modified file 'docs/index.rst'
--- docs/index.rst	2015-07-24 05:33:16 +0000
+++ docs/index.rst	2015-11-19 21:45:01 +0000
@@ -1,23 +1,33 @@
-.. Rutabaga documentation master file, created by
-   sphinx-quickstart on Thu Jul 16 11:11:38 2015.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to Rutabaga's documentation!
-====================================
-
-Contents:
+Rutabaga Documentation
+======================
+
+`Rutabaga <https://launchpad.net/rutabaga>`_ is comprised of a `Cornice
+<https://github.com/mozilla-services/cornice>`_
+REST API and Squid addon helper, providing time limited tokens for
+squid basic authentication to consuming services.
+
+Tokens can be manually revoked, or in a typical deployment scenario,
+revoked from a cron job. This is particularly useful in scenarios
+where consuming services may be running untrusted code but
+require restricted internet access for a particular process e.g. fetching
+a data payload, or software dependencies.
 
 .. toctree::
    :maxdepth: 2
 
-.. services::
-   :modules: rutabaga.views
-
-Indices and tables
+   getting_started
+   api
+
+
+
+Squid Addon Helper
+##################
+
+Rutabaga's `squid helper <http://bazaar.launchpad.net/~canonical-launchpad-branches/rutabaga/devel/view/head:/rutabaga/scripts/rutabaga_auth_helper.py>`_ conforms to the squid addon helper `basic auth protocol
+<http://wiki.squid-cache.org/Features/AddonHelpers#Basic_Scheme>`_.
+
+Search
 ==================
 
-* :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`