updating keystoneclient doc theme

adding in openstack theming
enabling last update from git
removing old manual references to API, converted entirely to autodoc
updated .gitignore
fixed docstring warnings and errors

Change-Id: Id22ddc446331d52cbf56c3462d8b532fc37f64ac

25 files changed, 1268 insertions, 120 deletions

diff --git a/.gitignore b/.gitignore
index 2c761aa..2169969 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,8 +6,10 @@ cover
 .idea
 *.swp
 *~
+.tox
 AUTHORS
 build
 dist
 python_keystoneclient.egg-info
 keystoneclient/versioninfo
+doc/source/api
diff --git a/doc/source/_templates/.placeholder b/doc/source/_templates/.placeholder
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/doc/source/_templates/.placeholder
diff --git a/doc/source/_theme/layout.html b/doc/source/_theme/layout.html
new file mode 100644
index 0000000..750b782
--- /dev/null
+++ b/doc/source/_theme/layout.html
@@ -0,0 +1,83 @@
+{% extends "basic/layout.html" %}
+{% set css_files = css_files + ['_static/tweaks.css'] %}
+{% set script_files = script_files + ['_static/jquery.tweet.js'] %}
+
+{%- macro sidebar() %}
+      {%- if not embedded %}{% if not theme_nosidebar|tobool %}
+      <div class="sphinxsidebar">
+        <div class="sphinxsidebarwrapper">
+          {%- block sidebarlogo %}
+          {%- if logo %}
+            <p class="logo"><a href="{{ pathto(master_doc) }}">
+              <img class="logo" src="{{ pathto('_static/' + logo, 1) }}" alt="Logo"/>
+            </a></p>
+          {%- endif %}
+          {%- endblock %}
+          {%- block sidebartoc %}
+          {%- if display_toc %}
+            <h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
+            {{ toc }}
+          {%- endif %}
+          {%- endblock %}
+          {%- block sidebarrel %}
+          {%- if prev %}
+            <h4>{{ _('Previous topic') }}</h4>
+            <p class="topless"><a href="{{ prev.link|e }}"
+                                  title="{{ _('previous chapter') }}">{{ prev.title }}</a></p>
+          {%- endif %}
+          {%- if next %}
+            <h4>{{ _('Next topic') }}</h4>
+            <p class="topless"><a href="{{ next.link|e }}"
+                                  title="{{ _('next chapter') }}">{{ next.title }}</a></p>
+          {%- endif %}
+          {%- endblock %}
+          {%- block sidebarsourcelink %}
+          {%- if show_source and has_source and sourcename %}
+            <h3>{{ _('This Page') }}</h3>
+            <ul class="this-page-menu">
+              <li><a href="{{ pathto('_sources/' + sourcename, true)|e }}"
+                     rel="nofollow">{{ _('Show Source') }}</a></li>
+            </ul>
+          {%- endif %}
+          {%- endblock %}
+          {%- if customsidebar %}
+          {% include customsidebar %}
+          {%- endif %}
+          {%- block sidebarsearch %}
+          {%- if pagename != "search" %}
+          <div id="searchbox" style="display: none">
+            <h3>{{ _('Quick search') }}</h3>
+              <form class="search" action="{{ pathto('search') }}" method="get">
+                <input type="text" name="q" size="18" />
+                <input type="submit" value="{{ _('Go') }}" />
+                <input type="hidden" name="check_keywords" value="yes" />
+                <input type="hidden" name="area" value="default" />
+              </form>
+              <p class="searchtip" style="font-size: 90%">
+              {{ _('Enter search terms or a module, class or function name.') }}
+              </p>
+          </div>
+          <script type="text/javascript">$('#searchbox').show(0);</script>
+          {%- endif %}
+          {%- endblock %}
+        </div>
+      </div>
+      {%- endif %}{% endif %}
+{%- endmacro %}
+
+{% block relbar1 %}{% endblock relbar1 %}
+
+{% block header %}
+  <div id="header">
+    <h1 id="logo"><a href="http://www.openstack.org/">OpenStack</a></h1>
+    <ul id="navigation">
+      <li><a href="http://www.openstack.org/" title="Go to the Home page" class="link">Home</a></li>
+      <li><a href="http://www.openstack.org/projects/" title="Go to the OpenStack Projects page">Projects</a></li>
+      <li><a href="http://www.openstack.org/user-stories/" title="Go to the User Stories page" class="link">User Stories</a></li>
+      <li><a href="http://www.openstack.org/community/" title="Go to the Community page" class="link">Community</a></li>
+      <li><a href="http://www.openstack.org/blog/" title="Go to the OpenStack Blog">Blog</a></li>
+      <li><a href="http://wiki.openstack.org/" title="Go to the OpenStack Wiki">Wiki</a></li>
+      <li><a href="http://docs.openstack.org/" title="Go to OpenStack Documentation" class="current">Documentation</a></li>
+    </ul>
+  </div>
+{% endblock %}
\ No newline at end of file
diff --git a/doc/source/_theme/theme.conf b/doc/source/_theme/theme.conf
new file mode 100644
index 0000000..1cc4004
--- /dev/null
+++ b/doc/source/_theme/theme.conf
@@ -0,0 +1,4 @@
+[theme]
+inherit = basic
+stylesheet = nature.css
+pygments_style = tango
diff --git a/doc/source/conf.py b/doc/source/conf.py
index b9c3d53..9486507 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -16,7 +16,7 @@ import os
 import sys
 
 sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__),
-                "..", "..")))
+                '..', '..')))
 
 # 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
@@ -28,7 +28,12 @@ sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__),
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']
+extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.todo',
+              'sphinx.ext.coverage',
+              'sphinx.ext.intersphinx']
+
+todo_include_todos = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -50,10 +55,10 @@ copyright = u'Rackspace, based on work by Jacob Kaplan-Moss'
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-# The short X.Y version.
-version = '2.7'
+# The short XXXX.Y version.
+version = '2012.3'
 # The full version, including alpha/beta/rc tags.
-release = '2.7.0'
+release = '2012.3-dev'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -98,7 +103,8 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'nature'
+html_theme_path = ["."]
+html_theme = '_theme'
 
 # 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
@@ -127,11 +133,12 @@ html_theme = 'nature'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ['static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
+git_cmd = "git log --pretty=format:'%ad, commit %h' --date=local -n1"
+html_last_updated_fmt = os.popen(git_cmd).read()
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@@ -181,8 +188,9 @@ htmlhelp_basename = 'python-keystoneclientdoc'
 # .
 latex_documents = [
     ('index', 'python-keystoneclient.tex',
-    u'python-keystoneclient Documentation',
-    u'Nebula Inc, based on work by Rackspace and Jacob Kaplan-Moss', 'manual'),
+     u'python-keystoneclient Documentation',
+     u'Nebula Inc, based on work by Rackspace and Jacob Kaplan-Moss',
+     'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -204,4 +212,7 @@ latex_documents = [
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'http://docs.python.org/': None}
+intersphinx_mapping = {'python': ('http://docs.python.org/', None),
+                       'nova': ('http://nova.openstack.org', None),
+                       'swift': ('http://swift.openstack.org', None),
+                       'glance': ('http://glance.openstack.org', None)}
diff --git a/doc/source/index.rst b/doc/source/index.rst
index bece0aa..51bc647 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -10,20 +10,21 @@ Contents:
 .. toctree::
    :maxdepth: 1
 
-   using-api
-   shell
-   ref/index
    releases
+   shell
+   using-api
+
+   api/autoindex
 
 Contributing
 ============
 
-Code is hosted `on GitHub`_. Submit bugs to the Keystone project on 
+Code is hosted `on GitHub`_. Submit bugs to the Keystone project on
 `Launchpad`_. Submit code to the openstack/python-keystoneclient project using
 `Gerrit`_.
 
 .. _on GitHub: https://github.com/openstack/python-keystoneclient
-.. _Launchpad: https://launchpad.net/keystone
+.. _Launchpad: https://launchpad.net/python-keystoneclient
 .. _Gerrit: http://wiki.openstack.org/GerritWorkflow
 
 Run tests with ``python setup.py test``.
diff --git a/doc/source/ref/client.rst b/doc/source/ref/client.rst
deleted file mode 100644
index cb21e3e..0000000
--- a/doc/source/ref/client.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-Client
-======
-
-.. currentmodule:: keystoneclient.v2_0.client
-
-.. autoclass:: Client
-
-    .. automethod:: authenticate
diff --git a/doc/source/ref/endpoints.rst b/doc/source/ref/endpoints.rst
deleted file mode 100644
index ed2b4e2..0000000
--- a/doc/source/ref/endpoints.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-==============================
-Endpoint Manager and Endpoints
-==============================
-
-
-
-.. currentmodule:: keystoneclient.v2_0.endpoints
-
-.. automodule:: keystoneclient.v2_0.endpoints
-    :members:
-
diff --git a/doc/source/ref/exceptions.rst b/doc/source/ref/exceptions.rst
deleted file mode 100644
index 988f7d0..0000000
--- a/doc/source/ref/exceptions.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-Exceptions
-==========
-
-.. currentmodule:: keystoneclient.exceptions
-
-.. automodule:: keystoneclient.exceptions
-    :members:
-
diff --git a/doc/source/ref/generic-client.rst b/doc/source/ref/generic-client.rst
deleted file mode 100644
index 9905558..0000000
--- a/doc/source/ref/generic-client.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-Generic client
-==============
-
-Use the generic client to obtain access to a specific endpoint version.
-
-
-.. currentmodule:: keystoneclient.generic.client
-
-.. autoclass:: Client
-
-    .. automethod:: discover
-
diff --git a/doc/source/ref/index.rst b/doc/source/ref/index.rst
deleted file mode 100644
index d99127e..0000000
--- a/doc/source/ref/index.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-API Reference
-=============
-
-The following API reference documents are available:
-
-.. toctree::
-   :maxdepth: 1
-
-   client
-   generic-client
-   tenants
-   users
-   roles
-   services
-   endpoints
-   exceptions
diff --git a/doc/source/ref/roles.rst b/doc/source/ref/roles.rst
deleted file mode 100644
index 9cb9283..0000000
--- a/doc/source/ref/roles.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-======================
-Role Manager and Roles
-======================
-
-.. currentmodule:: keystoneclient.v2_0.roles
-
-.. automodule:: keystoneclient.v2_0.roles
-    :members:
-
diff --git a/doc/source/ref/services.rst b/doc/source/ref/services.rst
deleted file mode 100644
index a4b677c..0000000
--- a/doc/source/ref/services.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-============================
-Service Manager and Services
-============================
-
-
-
-.. currentmodule:: keystoneclient.v2_0.services
-
-.. automodule:: keystoneclient.v2_0.services
-    :members:
-
diff --git a/doc/source/ref/tenants.rst b/doc/source/ref/tenants.rst
deleted file mode 100644
index d6e3861..0000000
--- a/doc/source/ref/tenants.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-==========================
-Tenant Manager and Tenants
-==========================
-
-
-
-.. currentmodule:: keystoneclient.v2_0.tenants
-
-.. automodule:: keystoneclient.v2_0.tenants
-    :members:
-
diff --git a/doc/source/ref/users.rst b/doc/source/ref/users.rst
deleted file mode 100644
index 953daec..0000000
--- a/doc/source/ref/users.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-======================
-User Manager and Users
-======================
-
-.. currentmodule:: keystoneclient.v2_0.users
-
-.. automodule:: keystoneclient.v2_0.users
-    :members:
-
diff --git a/doc/source/static/basic.css b/doc/source/static/basic.css
new file mode 100644
index 0000000..d909ce3
--- /dev/null
+++ b/doc/source/static/basic.css
@@ -0,0 +1,416 @@
+/**
+ * Sphinx stylesheet -- basic theme
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ */
+
+/* -- main layout ----------------------------------------------------------- */
+
+div.clearer {
+    clear: both;
+}
+
+/* -- relbar ---------------------------------------------------------------- */
+
+div.related {
+    width: 100%;
+    font-size: 90%;
+}
+
+div.related h3 {
+    display: none;
+}
+
+div.related ul {
+    margin: 0;
+    padding: 0 0 0 10px;
+    list-style: none;
+}
+
+div.related li {
+    display: inline;
+}
+
+div.related li.right {
+    float: right;
+    margin-right: 5px;
+}
+
+/* -- sidebar --------------------------------------------------------------- */
+
+div.sphinxsidebarwrapper {
+    padding: 10px 5px 0 10px;
+}
+
+div.sphinxsidebar {
+    float: left;
+    width: 230px;
+    margin-left: -100%;
+    font-size: 90%;
+}
+
+div.sphinxsidebar ul {
+    list-style: none;
+}
+
+div.sphinxsidebar ul ul,
+div.sphinxsidebar ul.want-points {
+    margin-left: 20px;
+    list-style: square;
+}
+
+div.sphinxsidebar ul ul {
+    margin-top: 0;
+    margin-bottom: 0;
+}
+
+div.sphinxsidebar form {
+    margin-top: 10px;
+}
+
+div.sphinxsidebar input {
+    border: 1px solid #98dbcc;
+    font-family: sans-serif;
+    font-size: 1em;
+}
+
+img {
+    border: 0;
+}
+
+/* -- search page ----------------------------------------------------------- */
+
+ul.search {
+    margin: 10px 0 0 20px;
+    padding: 0;
+}
+
+ul.search li {
+    padding: 5px 0 5px 20px;
+    background-image: url(file.png);
+    background-repeat: no-repeat;
+    background-position: 0 7px;
+}
+
+ul.search li a {
+    font-weight: bold;
+}
+
+ul.search li div.context {
+    color: #888;
+    margin: 2px 0 0 30px;
+    text-align: left;
+}
+
+ul.keywordmatches li.goodmatch a {
+    font-weight: bold;
+}
+
+/* -- index page ------------------------------------------------------------ */
+
+table.contentstable {
+    width: 90%;
+}
+
+table.contentstable p.biglink {
+    line-height: 150%;
+}
+
+a.biglink {
+    font-size: 1.3em;
+}
+
+span.linkdescr {
+    font-style: italic;
+    padding-top: 5px;
+    font-size: 90%;
+}
+
+/* -- general index --------------------------------------------------------- */
+
+table.indextable td {
+    text-align: left;
+    vertical-align: top;
+}
+
+table.indextable dl, table.indextable dd {
+    margin-top: 0;
+    margin-bottom: 0;
+}
+
+table.indextable tr.pcap {
+    height: 10px;
+}
+
+table.indextable tr.cap {
+    margin-top: 10px;
+    background-color: #f2f2f2;
+}
+
+img.toggler {
+    margin-right: 3px;
+    margin-top: 3px;
+    cursor: pointer;
+}
+
+/* -- general body styles --------------------------------------------------- */
+
+a.headerlink {
+    visibility: hidden;
+}
+
+h1:hover > a.headerlink,
+h2:hover > a.headerlink,
+h3:hover > a.headerlink,
+h4:hover > a.headerlink,
+h5:hover > a.headerlink,
+h6:hover > a.headerlink,
+dt:hover > a.headerlink {
+    visibility: visible;
+}
+
+div.body p.caption {
+    text-align: inherit;
+}
+
+div.body td {
+    text-align: left;
+}
+
+.field-list ul {
+    padding-left: 1em;
+}
+
+.first {
+}
+
+p.rubric {
+    margin-top: 30px;
+    font-weight: bold;
+}
+
+/* -- sidebars -------------------------------------------------------------- */
+
+div.sidebar {
+    margin: 0 0 0.5em 1em;
+    border: 1px solid #ddb;
+    padding: 7px 7px 0 7px;
+    background-color: #ffe;
+    width: 40%;
+    float: right;
+}
+
+p.sidebar-title {
+    font-weight: bold;
+}
+
+/* -- topics ---------------------------------------------------------------- */
+
+div.topic {
+    border: 1px solid #ccc;
+    padding: 7px 7px 0 7px;
+    margin: 10px 0 10px 0;
+}
+
+p.topic-title {
+    font-size: 1.1em;
+    font-weight: bold;
+    margin-top: 10px;
+}
+
+/* -- admonitions ----------------------------------------------------------- */
+
+div.admonition {
+    margin-top: 10px;
+    margin-bottom: 10px;
+    padding: 7px;
+}
+
+div.admonition dt {
+    font-weight: bold;
+}
+
+div.admonition dl {
+    margin-bottom: 0;
+}
+
+p.admonition-title {
+    margin: 0px 10px 5px 0px;
+    font-weight: bold;
+}
+
+div.body p.centered {
+    text-align: center;
+    margin-top: 25px;
+}
+
+/* -- tables ---------------------------------------------------------------- */
+
+table.docutils {
+    border: 0;
+    border-collapse: collapse;
+}
+
+table.docutils td, table.docutils th {
+    padding: 1px 8px 1px 0;
+    border-top: 0;
+    border-left: 0;
+    border-right: 0;
+    border-bottom: 1px solid #aaa;
+}
+
+table.field-list td, table.field-list th {
+    border: 0 !important;
+}
+
+table.footnote td, table.footnote th {
+    border: 0 !important;
+}
+
+th {
+    text-align: left;
+    padding-right: 5px;
+}
+
+/* -- other body styles ----------------------------------------------------- */
+
+dl {
+    margin-bottom: 15px;
+}
+
+dd p {
+    margin-top: 0px;
+}
+
+dd ul, dd table {
+    margin-bottom: 10px;
+}
+
+dd {
+    margin-top: 3px;
+    margin-bottom: 10px;
+    margin-left: 30px;
+}
+
+dt:target, .highlight {
+    background-color: #fbe54e;
+}
+
+dl.glossary dt {
+    font-weight: bold;
+    font-size: 1.1em;
+}
+
+.field-list ul {
+    margin: 0;
+    padding-left: 1em;
+}
+
+.field-list p {
+    margin: 0;
+}
+
+.refcount {
+    color: #060;
+}
+
+.optional {
+    font-size: 1.3em;
+}
+
+.versionmodified {
+    font-style: italic;
+}
+
+.system-message {
+    background-color: #fda;
+    padding: 5px;
+    border: 3px solid red;
+}
+
+.footnote:target  {
+    background-color: #ffa
+}
+
+.line-block {
+    display: block;
+    margin-top: 1em;
+    margin-bottom: 1em;
+}
+
+.line-block .line-block {
+    margin-top: 0;
+    margin-bottom: 0;
+    margin-left: 1.5em;
+}
+
+/* -- code displays --------------------------------------------------------- */
+
+pre {
+    overflow: auto;
+}
+
+td.linenos pre {
+    padding: 5px 0px;
+    border: 0;
+    background-color: transparent;
+    color: #aaa;
+}
+
+table.highlighttable {
+    margin-left: 0.5em;
+}
+
+table.highlighttable td {
+    padding: 0 0.5em 0 0.5em;
+}
+
+tt.descname {
+    background-color: transparent;
+    font-weight: bold;
+    font-size: 1.2em;
+}
+
+tt.descclassname {
+    background-color: transparent;
+}
+
+tt.xref, a tt {
+    background-color: transparent;
+    font-weight: bold;
+}
+
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
+    background-color: transparent;
+}
+
+/* -- math display ---------------------------------------------------------- */
+
+img.math {
+    vertical-align: middle;
+}
+
+div.body div.math p {
+    text-align: center;
+}
+
+span.eqno {
+    float: right;
+}
+
+/* -- printout stylesheet --------------------------------------------------- */
+
+@media print {
+    div.document,
+    div.documentwrapper,
+    div.bodywrapper {
+        margin: 0 !important;
+        width: 100%;
+    }
+
+    div.sphinxsidebar,
+    div.related,
+    div.footer,
+    #top-link {
+        display: none;
+    }
+}
diff --git a/doc/source/static/default.css b/doc/source/static/default.css
new file mode 100644
index 0000000..c8091ec
--- /dev/null
+++ b/doc/source/static/default.css
@@ -0,0 +1,230 @@
+/**
+ * Sphinx stylesheet -- default theme
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ */
+
+@import url("basic.css");
+
+/* -- page layout ----------------------------------------------------------- */
+
+body {
+    font-family: sans-serif;
+    font-size: 100%;
+    background-color: #11303d;
+    color: #000;
+    margin: 0;
+    padding: 0;
+}
+
+div.document {
+    background-color: #1c4e63;
+}
+
+div.documentwrapper {
+    float: left;
+    width: 100%;
+}
+
+div.bodywrapper {
+    margin: 0 0 0 230px;
+}
+
+div.body {
+    background-color: #ffffff;
+    color: #000000;
+    padding: 0 20px 30px 20px;
+}
+
+div.footer {
+    color: #ffffff;
+    width: 100%;
+    padding: 9px 0 9px 0;
+    text-align: center;
+    font-size: 75%;
+}
+
+div.footer a {
+    color: #ffffff;
+    text-decoration: underline;
+}
+
+div.related {
+    background-color: #133f52;
+    line-height: 30px;
+    color: #ffffff;
+}
+
+div.related a {
+    color: #ffffff;
+}
+
+div.sphinxsidebar {
+}
+
+div.sphinxsidebar h3 {
+    font-family: 'Trebuchet MS', sans-serif;
+    color: #ffffff;
+    font-size: 1.4em;
+    font-weight: normal;
+    margin: 0;
+    padding: 0;
+}
+
+div.sphinxsidebar h3 a {
+    color: #ffffff;
+}
+
+div.sphinxsidebar h4 {
+    font-family: 'Trebuchet MS', sans-serif;
+    color: #ffffff;
+    font-size: 1.3em;
+    font-weight: normal;
+    margin: 5px 0 0 0;
+    padding: 0;
+}
+
+div.sphinxsidebar p {
+    color: #ffffff;
+}
+
+div.sphinxsidebar p.topless {
+    margin: 5px 10px 10px 10px;
+}
+
+div.sphinxsidebar ul {
+    margin: 10px;
+    padding: 0;
+    color: #ffffff;
+}
+
+div.sphinxsidebar a {
+    color: #98dbcc;
+}
+
+div.sphinxsidebar input {
+    border: 1px solid #98dbcc;
+    font-family: sans-serif;
+    font-size: 1em;
+}
+
+/* -- body styles ----------------------------------------------------------- */
+
+a {
+    color: #355f7c;
+    text-decoration: none;
+}
+
+a:hover {
+    text-decoration: underline;
+}
+
+div.body p, div.body dd, div.body li {
+    text-align: left;
+    line-height: 130%;
+}
+
+div.body h1,
+div.body h2,
+div.body h3,
+div.body h4,
+div.body h5,
+div.body h6 {
+    font-family: 'Trebuchet MS', sans-serif;
+    background-color: #f2f2f2;
+    font-weight: normal;
+    color: #20435c;
+    border-bottom: 1px solid #ccc;
+    margin: 20px -20px 10px -20px;
+    padding: 3px 0 3px 10px;
+}
+
+div.body h1 { margin-top: 0; font-size: 200%; }
+div.body h2 { font-size: 160%; }
+div.body h3 { font-size: 140%; }
+div.body h4 { font-size: 120%; }
+div.body h5 { font-size: 110%; }
+div.body h6 { font-size: 100%; }
+
+a.headerlink {
+    color: #c60f0f;
+    font-size: 0.8em;
+    padding: 0 4px 0 4px;
+    text-decoration: none;
+}
+
+a.headerlink:hover {
+    background-color: #c60f0f;
+    color: white;
+}
+
+div.body p, div.body dd, div.body li {
+    text-align: left;
+    line-height: 130%;
+}
+
+div.admonition p.admonition-title + p {
+    display: inline;
+}
+
+div.admonition p {
+    margin-bottom: 5px;
+}
+
+div.admonition pre {
+    margin-bottom: 5px;
+}
+
+div.admonition ul, div.admonition ol {
+    margin-bottom: 5px;
+}
+
+div.note {
+    background-color: #eee;
+    border: 1px solid #ccc;
+}
+
+div.seealso {
+    background-color: #ffc;
+    border: 1px solid #ff6;
+}
+
+div.topic {
+    background-color: #eee;
+}
+
+div.warning {
+    background-color: #ffe4e4;
+    border: 1px solid #f66;
+}
+
+p.admonition-title {
+    display: inline;
+}
+
+p.admonition-title:after {
+    content: ":";
+}
+
+pre {
+    padding: 5px;
+    background-color: #eeffcc;
+    color: #333333;
+    line-height: 120%;
+    border: 1px solid #ac9;
+    border-left: none;
+    border-right: none;
+}
+
+tt {
+    background-color: #ecf0f3;
+    padding: 0 1px 0 1px;
+    font-size: 0.95em;
+}
+
+.warning tt {
+    background: #efc2c2;
+}
+
+.note tt {
+    background: #d6d6d6;
+}
diff --git a/doc/source/static/header-line.gif b/doc/source/static/header-line.gif
new file mode 100644
index 0000000..3601730
--- /dev/null
+++ b/doc/source/static/header-line.gif
diff --git a/doc/source/static/header_bg.jpg b/doc/source/static/header_bg.jpg
new file mode 100644
index 0000000..f788c41
--- /dev/null
+++ b/doc/source/static/header_bg.jpg
diff --git a/doc/source/static/jquery.tweet.js b/doc/source/static/jquery.tweet.js
new file mode 100644
index 0000000..79bf0bd
--- /dev/null
+++ b/doc/source/static/jquery.tweet.js
@@ -0,0 +1,154 @@
+(function($) {
+
+  $.fn.tweet = function(o){
+    var s = {
+      username: ["seaofclouds"],              // [string]   required, unless you want to display our tweets. :) it can be an array, just do ["username1","username2","etc"]
+      list: null,                              //[string]   optional name of list belonging to username
+      avatar_size: null,                      // [integer]  height and width of avatar if displayed (48px max)
+      count: 3,                               // [integer]  how many tweets to display?
+      intro_text: null,                       // [string]   do you want text BEFORE your your tweets?
+      outro_text: null,                       // [string]   do you want text AFTER your tweets?
+      join_text:  null,                       // [string]   optional text in between date and tweet, try setting to "auto"
+      auto_join_text_default: "i said,",      // [string]   auto text for non verb: "i said" bullocks
+      auto_join_text_ed: "i",                 // [string]   auto text for past tense: "i" surfed
+      auto_join_text_ing: "i am",             // [string]   auto tense for present tense: "i was" surfing
+      auto_join_text_reply: "i replied to",   // [string]   auto tense for replies: "i replied to" @someone "with"
+      auto_join_text_url: "i was looking at", // [string]   auto tense for urls: "i was looking at" http:...
+      loading_text: null,                     // [string]   optional loading text, displayed while tweets load
+      query: null                             // [string]   optional search query
+    };
+
+    if(o) $.extend(s, o);
+
+    $.fn.extend({
+      linkUrl: function() {
+        var returning = [];
+        var regexp = /((ftp|http|https):\/\/(\w+:{0,1}\w*@)?(\S+)(:[0-9]+)?(\/|\/([\w#!:.?+=&%@!\-\/]))?)/gi;
+        this.each(function() {
+          returning.push(this.replace(regexp,"<a href=\"$1\">$1</a>"));
+        });
+        return $(returning);
+      },
+      linkUser: function() {
+        var returning = [];
+        var regexp = /[\@]+([A-Za-z0-9-_]+)/gi;
+        this.each(function() {
+          returning.push(this.replace(regexp,"<a href=\"http://twitter.com/$1\">@$1</a>"));
+        });
+        return $(returning);
+      },
+      linkHash: function() {
+        var returning = [];
+        var regexp = / [\#]+([A-Za-z0-9-_]+)/gi;
+        this.each(function() {
+          returning.push(this.replace(regexp, ' <a href="http://search.twitter.com/search?q=&tag=$1&lang=all&from='+s.username.join("%2BOR%2B")+'">#$1</a>'));
+        });
+        return $(returning);
+      },
+      capAwesome: function() {
+        var returning = [];
+        this.each(function() {
+          returning.push(this.replace(/\b(awesome)\b/gi, '<span class="awesome">$1</span>'));
+        });
+        return $(returning);
+      },
+      capEpic: function() {
+        var returning = [];
+        this.each(function() {
+          returning.push(this.replace(/\b(epic)\b/gi, '<span class="epic">$1</span>'));
+        });
+        return $(returning);
+      },
+      makeHeart: function() {
+        var returning = [];
+        this.each(function() {
+          returning.push(this.replace(/(&lt;)+[3]/gi, "<tt class='heart'>&#x2665;</tt>"));
+        });
+        return $(returning);
+      }
+    });
+
+    function relative_time(time_value) {
+      var parsed_date = Date.parse(time_value);
+      var relative_to = (arguments.length > 1) ? arguments[1] : new Date();
+      var delta = parseInt((relative_to.getTime() - parsed_date) / 1000);
+      var pluralize = function (singular, n) {
+        return '' + n + ' ' + singular + (n == 1 ? '' : 's');
+      };
+      if(delta < 60) {
+      return 'less than a minute ago';
+      } else if(delta < (45*60)) {
+      return 'about ' + pluralize("minute", parseInt(delta / 60)) + ' ago';
+      } else if(delta < (24*60*60)) {
+      return 'about ' + pluralize("hour", parseInt(delta / 3600)) + ' ago';
+      } else {
+      return 'about ' + pluralize("day", parseInt(delta / 86400)) + ' ago';
+      }
+    }
+
+    function build_url() {
+      var proto = ('https:' == document.location.protocol ? 'https:' : 'http:');
+      if (s.list) {
+        return proto+"//api.twitter.com/1/"+s.username[0]+"/lists/"+s.list+"/statuses.json?per_page="+s.count+"&callback=?";
+      } else if (s.query == null && s.username.length == 1) {
+        return proto+'//twitter.com/status/user_timeline/'+s.username[0]+'.json?count='+s.count+'&callback=?';
+      } else {
+        var query = (s.query || 'from:'+s.username.join('%20OR%20from:'));
+        return proto+'//search.twitter.com/search.json?&q='+query+'&rpp='+s.count+'&callback=?';
+      }
+    }
+
+    return this.each(function(){
+      var list = $('<ul class="tweet_list">').appendTo(this);
+      var intro = '<p class="tweet_intro">'+s.intro_text+'</p>';
+      var outro = '<p class="tweet_outro">'+s.outro_text+'</p>';
+      var loading = $('<p class="loading">'+s.loading_text+'</p>');
+
+      if(typeof(s.username) == "string"){
+        s.username = [s.username];
+      }
+
+      if (s.loading_text) $(this).append(loading);
+      $.getJSON(build_url(), function(data){
+        if (s.loading_text) loading.remove();
+        if (s.intro_text) list.before(intro);
+        $.each((data.results || data), function(i,item){
+          // auto join text based on verb tense and content
+          if (s.join_text == "auto") {
+            if (item.text.match(/^(@([A-Za-z0-9-_]+)) .*/i)) {
+              var join_text = s.auto_join_text_reply;
+            } else if (item.text.match(/(^\w+:\/\/[A-Za-z0-9-_]+\.[A-Za-z0-9-_:%&\?\/.=]+) .*/i)) {
+              var join_text = s.auto_join_text_url;
+            } else if (item.text.match(/^((\w+ed)|just) .*/im)) {
+              var join_text = s.auto_join_text_ed;
+            } else if (item.text.match(/^(\w*ing) .*/i)) {
+              var join_text = s.auto_join_text_ing;
+            } else {
+              var join_text = s.auto_join_text_default;
+            }
+          } else {
+            var join_text = s.join_text;
+          };
+
+          var from_user = item.from_user || item.user.screen_name;
+          var profile_image_url = item.profile_image_url || item.user.profile_image_url;
+          var join_template = '<span class="tweet_join"> '+join_text+' </span>';
+          var join = ((s.join_text) ? join_template : ' ');
+          var avatar_template = '<a class="tweet_avatar" href="http://twitter.com/'+from_user+'"><img src="'+profile_image_url+'" height="'+s.avatar_size+'" width="'+s.avatar_size+'" alt="'+from_user+'\'s avatar" title="'+from_user+'\'s avatar" border="0"/></a>';
+          var avatar = (s.avatar_size ? avatar_template : '');
+          var date = '<a href="http://twitter.com/'+from_user+'/statuses/'+item.id+'" title="view tweet on twitter">'+relative_time(item.created_at)+'</a>';
+          var text = '<span class="tweet_text">' +$([item.text]).linkUrl().linkUser().linkHash().makeHeart().capAwesome().capEpic()[0]+ '</span>';
+
+          // until we create a template option, arrange the items below to alter a tweet's display.
+          list.append('<li>' + avatar + date + join + text + '</li>');
+
+          list.children('li:first').addClass('tweet_first');
+          list.children('li:odd').addClass('tweet_even');
+          list.children('li:even').addClass('tweet_odd');
+        });
+        if (s.outro_text) list.after(outro);
+      });
+
+    });
+  };
+})(jQuery);
\ No newline at end of file
diff --git a/doc/source/static/nature.css b/doc/source/static/nature.css
new file mode 100644
index 0000000..a98bd42
--- /dev/null
+++ b/doc/source/static/nature.css
@@ -0,0 +1,245 @@
+/*
+ * nature.css_t
+ * ~~~~~~~~~~~~
+ *
+ * Sphinx stylesheet -- nature theme.
+ *
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+ 
+@import url("basic.css");
+ 
+/* -- page layout ----------------------------------------------------------- */
+ 
+body {
+    font-family: Arial, sans-serif;
+    font-size: 100%;
+    background-color: #111;
+    color: #555;
+    margin: 0;
+    padding: 0;
+}
+
+div.documentwrapper {
+    float: left;
+    width: 100%;
+}
+
+div.bodywrapper {
+    margin: 0 0 0 {{ theme_sidebarwidth|toint }}px;
+}
+
+hr {
+    border: 1px solid #B1B4B6;
+}
+ 
+div.document {
+    background-color: #eee;
+}
+ 
+div.body {
+    background-color: #ffffff;
+    color: #3E4349;
+    padding: 0 30px 30px 30px;
+    font-size: 0.9em;
+}
+ 
+div.footer {
+    color: #555;
+    width: 100%;
+    padding: 13px 0;
+    text-align: center;
+    font-size: 75%;
+}
+ 
+div.footer a {
+    color: #444;
+    text-decoration: underline;
+}
+ 
+div.related {
+    background-color: #6BA81E;
+    line-height: 32px;
+    color: #fff;
+    text-shadow: 0px 1px 0 #444;
+    font-size: 0.9em;
+}
+ 
+div.related a {
+    color: #E2F3CC;
+}
+ 
+div.sphinxsidebar {
+    font-size: 0.75em;
+    line-height: 1.5em;
+}
+
+div.sphinxsidebarwrapper{
+    padding: 20px 0;
+}
+ 
+div.sphinxsidebar h3,
+div.sphinxsidebar h4 {
+    font-family: Arial, sans-serif;
+    color: #222;
+    font-size: 1.2em;
+    font-weight: normal;
+    margin: 0;
+    padding: 5px 10px;
+    background-color: #ddd;
+    text-shadow: 1px 1px 0 white
+}
+
+div.sphinxsidebar h4{
+    font-size: 1.1em;
+}
+ 
+div.sphinxsidebar h3 a {
+    color: #444;
+}
+ 
+ 
+div.sphinxsidebar p {
+    color: #888;
+    padding: 5px 20px;
+}
+ 
+div.sphinxsidebar p.topless {
+}
+ 
+div.sphinxsidebar ul {
+    margin: 10px 20px;
+    padding: 0;
+    color: #000;
+}
+ 
+div.sphinxsidebar a {
+    color: #444;
+}
+ 
+div.sphinxsidebar input {
+    border: 1px solid #ccc;
+    font-family: sans-serif;
+    font-size: 1em;
+}
+
+div.sphinxsidebar input[type=text]{
+    margin-left: 20px;
+}
+ 
+/* -- body styles ----------------------------------------------------------- */
+ 
+a {
+    color: #005B81;
+    text-decoration: none;
+}
+ 
+a:hover {
+    color: #E32E00;
+    text-decoration: underline;
+}
+ 
+div.body h1,
+div.body h2,
+div.body h3,
+div.body h4,
+div.body h5,
+div.body h6 {
+    font-family: Arial, sans-serif;
+    background-color: #BED4EB;
+    font-weight: normal;
+    color: #212224;
+    margin: 30px 0px 10px 0px;
+    padding: 5px 0 5px 10px;
+    text-shadow: 0px 1px 0 white
+}
+ 
+div.body h1 { border-top: 20px solid white; margin-top: 0; font-size: 200%; }
+div.body h2 { font-size: 150%; background-color: #C8D5E3; }
+div.body h3 { font-size: 120%; background-color: #D8DEE3; }
+div.body h4 { font-size: 110%; background-color: #D8DEE3; }
+div.body h5 { font-size: 100%; background-color: #D8DEE3; }
+div.body h6 { font-size: 100%; background-color: #D8DEE3; }
+ 
+a.headerlink {
+    color: #c60f0f;
+    font-size: 0.8em;
+    padding: 0 4px 0 4px;
+    text-decoration: none;
+}
+ 
+a.headerlink:hover {
+    background-color: #c60f0f;
+    color: white;
+}
+ 
+div.body p, div.body dd, div.body li {
+    line-height: 1.5em;
+}
+ 
+div.admonition p.admonition-title + p {
+    display: inline;
+}
+
+div.highlight{
+    background-color: white;
+}
+
+div.note {
+    background-color: #eee;
+    border: 1px solid #ccc;
+}
+ 
+div.seealso {
+    background-color: #ffc;
+    border: 1px solid #ff6;
+}
+ 
+div.topic {
+    background-color: #eee;
+}
+ 
+div.warning {
+    background-color: #ffe4e4;
+    border: 1px solid #f66;
+}
+ 
+p.admonition-title {
+    display: inline;
+}
+ 
+p.admonition-title:after {
+    content: ":";
+}
+ 
+pre {
+    padding: 10px;
+    background-color: White;
+    color: #222;
+    line-height: 1.2em;
+    border: 1px solid #C6C9CB;
+    font-size: 1.1em;
+    margin: 1.5em 0 1.5em 0;
+    -webkit-box-shadow: 1px 1px 1px #d8d8d8;
+    -moz-box-shadow: 1px 1px 1px #d8d8d8;
+}
+ 
+tt {
+    background-color: #ecf0f3;
+    color: #222;
+    /* padding: 1px 2px; */
+    font-size: 1.1em;
+    font-family: monospace;
+}
+
+.viewcode-back {
+    font-family: Arial, sans-serif;
+}
+
+div.viewcode-block:target {
+    background-color: #f4debf;
+    border-top: 1px solid #ac9;
+    border-bottom: 1px solid #ac9;
+}
diff --git a/doc/source/static/openstack_logo.png b/doc/source/static/openstack_logo.png
new file mode 100644
index 0000000..146faec
--- /dev/null
+++ b/doc/source/static/openstack_logo.png
diff --git a/doc/source/static/tweaks.css b/doc/source/static/tweaks.css
new file mode 100644
index 0000000..3f3fb3f
--- /dev/null
+++ b/doc/source/static/tweaks.css
@@ -0,0 +1,94 @@
+body {
+  background: #fff url(../_static/header_bg.jpg) top left no-repeat;
+}
+
+#header {
+  width: 950px;
+  margin: 0 auto;
+  height: 102px;
+}
+
+#header h1#logo {
+  background: url(../_static/openstack_logo.png) top left no-repeat;
+  display: block;
+  float: left;
+  text-indent: -9999px;
+  width: 175px;
+  height: 55px;
+}
+
+#navigation {
+  background: url(../_static/header-line.gif) repeat-x 0 bottom;
+  display: block;
+  float: left;
+  margin: 27px 0 0 25px;
+  padding: 0;
+}
+
+#navigation li{
+  float: left;
+  display: block;
+  margin-right: 25px;
+}
+
+#navigation li a {
+  display: block;
+  font-weight: normal;
+  text-decoration: none;
+  background-position: 50% 0;
+  padding: 20px 0 5px;
+  color: #353535;
+  font-size: 14px;
+}
+
+#navigation li a.current, #navigation li a.section {
+  border-bottom: 3px solid #cf2f19;
+  color: #cf2f19;
+}
+
+div.related {
+  background-color: #cde2f8;
+  border: 1px solid #b0d3f8;
+}
+
+div.related a {
+  color: #4078ba;
+  text-shadow: none;
+}
+
+div.sphinxsidebarwrapper {
+  padding-top: 0;
+}
+
+pre {
+  color: #555;
+}
+
+div.documentwrapper h1, div.documentwrapper h2, div.documentwrapper h3, div.documentwrapper h4, div.documentwrapper h5, div.documentwrapper h6 {
+  font-family: 'PT Sans', sans-serif !important;
+  color: #264D69;
+  border-bottom: 1px dotted #C5E2EA;
+  padding: 0;
+  background: none;
+  padding-bottom: 5px;
+}
+
+div.documentwrapper h3 {
+  color: #CF2F19;
+}
+
+a.headerlink {
+  color: #fff !important;
+  margin-left: 5px;
+  background: #CF2F19 !important;
+}
+
+div.body {
+  margin-top: -25px;
+  margin-left: 230px;
+}
+
+div.document {
+  width: 960px;
+  margin: 0 auto;
+}
\ No newline at end of file
diff --git a/keystoneclient/generic/shell.py b/keystoneclient/generic/shell.py
index 16854f1..90fa4fd 100644
--- a/keystoneclient/generic/shell.py
+++ b/keystoneclient/generic/shell.py
@@ -28,13 +28,15 @@ def do_discover(cs, args):
     extensions supported.
 
     Usage::
-    $ keystone discover
-    Keystone found at http://localhost:35357
-        - supports version v1.0 (DEPRECATED) here http://localhost:35357/v1.0
-        - supports version v1.1 (CURRENT) here http://localhost:35357/v1.1
-        - supports version v2.0 (BETA) here http://localhost:35357/v2.0
-            - and RAX-KSKEY: Rackspace API Key Authentication Admin Extension
-            - and RAX-KSGRP: Rackspace Keystone Group Extensions
+
+        $ keystone discover
+        Keystone found at http://localhost:35357
+
+    - supports version v1.0 (DEPRECATED) here http://localhost:35357/v1.0
+    - supports version v1.1 (CURRENT) here http://localhost:35357/v1.1
+    - supports version v2.0 (CURRENT) here http://localhost:35357/v2.0
+        - and RAX-KSKEY: Rackspace API Key Authentication Admin Extension
+        - and RAX-KSGRP: Rackspace Keystone Group Extensions
     """
     if cs.endpoint:
         versions = cs.discover(cs.endpoint)
diff --git a/keystoneclient/utils.py b/keystoneclient/utils.py
index 4c439d7..0c9d34d 100644
--- a/keystoneclient/utils.py
+++ b/keystoneclient/utils.py
@@ -88,9 +88,10 @@ def find_resource(manager, name_or_id):
 
 
 def unauthenticated(f):
-    """ Adds 'unauthenticated' attribute to decorated function.
+    """Adds 'unauthenticated' attribute to decorated function.
+
+    Usage::
 
-    Usage:
         @unauthenticated
         def mymethod(f):
             ...