Move docs to doc.

To better facilitate the building and publishing of sphinx
documentation by Jenkins we are moving all openstack projects with
sphinx documentation to a common doc tree structure. Documentation
goes in project/doc/source and build results go in project/doc/build.

Change-Id: I205e8bb1ddf6dae1d7392b32975319c6a6d98673

14 files changed, 606 insertions, 0 deletions

diff --git a/doc/source/conf.py b/doc/source/conf.py
new file mode 100644
index 0000000..15112e7
--- /dev/null
+++ b/doc/source/conf.py
@@ -0,0 +1,200 @@
+# -*- coding: utf-8 -*-
+#
+# python-keystoneclient documentation build configuration file, created by
+# sphinx-quickstart on Sun Dec  6 14:19:25 2009.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+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
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.append(os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# 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']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'python-keystoneclient'
+copyright = u'Rackspace, based on work by Jacob Kaplan-Moss'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '2.7'
+# The full version, including alpha/beta/rc tags.
+release = '2.7.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directory, that shouldn't be searched
+# for source files.
+exclude_trees = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+html_theme = 'nature'
+
+# 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
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# 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']
+
+# 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'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'python-keystoneclientdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'python-keystoneclient.tex', 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
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {'http://docs.python.org/': None}
diff --git a/doc/source/index.rst b/doc/source/index.rst
new file mode 100644
index 0000000..bece0aa
--- /dev/null
+++ b/doc/source/index.rst
@@ -0,0 +1,37 @@
+Python bindings to the OpenStack Keystone API
+==================================================
+
+This is a client for OpenStack Keystone API. There's :doc:`a Python API
+<using-api>` (the :mod:`keystoneclient` module), and a :doc:`command-line script
+<shell>` (installed as :program:`keystone`).
+
+Contents:
+
+.. toctree::
+   :maxdepth: 1
+
+   using-api
+   shell
+   ref/index
+   releases
+
+Contributing
+============
+
+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
+.. _Gerrit: http://wiki.openstack.org/GerritWorkflow
+
+Run tests with ``python setup.py test``.
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
diff --git a/doc/source/ref/client.rst b/doc/source/ref/client.rst
new file mode 100644
index 0000000..cb21e3e
--- /dev/null
+++ b/doc/source/ref/client.rst
@@ -0,0 +1,8 @@
+Client
+======
+
+.. currentmodule:: keystoneclient.v2_0.client
+
+.. autoclass:: Client
+
+    .. automethod:: authenticate
diff --git a/doc/source/ref/endpoints.rst b/doc/source/ref/endpoints.rst
new file mode 100644
index 0000000..ed2b4e2
--- /dev/null
+++ b/doc/source/ref/endpoints.rst
@@ -0,0 +1,11 @@
+==============================
+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
new file mode 100644
index 0000000..988f7d0
--- /dev/null
+++ b/doc/source/ref/exceptions.rst
@@ -0,0 +1,8 @@
+Exceptions
+==========
+
+.. currentmodule:: keystoneclient.exceptions
+
+.. automodule:: keystoneclient.exceptions
+    :members:
+
diff --git a/doc/source/ref/generic-client.rst b/doc/source/ref/generic-client.rst
new file mode 100644
index 0000000..9905558
--- /dev/null
+++ b/doc/source/ref/generic-client.rst
@@ -0,0 +1,12 @@
+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
new file mode 100644
index 0000000..d99127e
--- /dev/null
+++ b/doc/source/ref/index.rst
@@ -0,0 +1,16 @@
+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
new file mode 100644
index 0000000..9cb9283
--- /dev/null
+++ b/doc/source/ref/roles.rst
@@ -0,0 +1,9 @@
+======================
+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
new file mode 100644
index 0000000..a4b677c
--- /dev/null
+++ b/doc/source/ref/services.rst
@@ -0,0 +1,11 @@
+============================
+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
new file mode 100644
index 0000000..d6e3861
--- /dev/null
+++ b/doc/source/ref/tenants.rst
@@ -0,0 +1,11 @@
+==========================
+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
new file mode 100644
index 0000000..953daec
--- /dev/null
+++ b/doc/source/ref/users.rst
@@ -0,0 +1,9 @@
+======================
+User Manager and Users
+======================
+
+.. currentmodule:: keystoneclient.v2_0.users
+
+.. automodule:: keystoneclient.v2_0.users
+    :members:
+
diff --git a/doc/source/releases.rst b/doc/source/releases.rst
new file mode 100644
index 0000000..4a9d281
--- /dev/null
+++ b/doc/source/releases.rst
@@ -0,0 +1,106 @@
+=============
+Release notes
+=============
+
+2.7.0 (October 21, 2011)
+========================
+* Forked from http://github.com/rackspace/python-novaclient
+* Rebranded to python-keystoneclient
+* Refactored to support Keystone API (auth, tokens, services, roles, tenants,
+  users, etc.)
+
+2.5.8 (July 11, 2011)
+=====================
+* returns all public/private ips, not just first one
+* better 'nova list' search options
+
+2.5.7 - 2.5.6 = minor tweaks
+
+2.5.5 (June 21, 2011)
+=====================
+* zone-boot min/max instance count added thanks to comstud
+* create for user added thanks to cerberus
+* fixed tests
+
+2.5.3 (June 15, 2011)
+=====================
+* ProjectID can be None for backwards compatability.
+* README/docs updated for projectId thanks to usrleon
+
+2.5.1 (June 10, 2011)
+=====================
+* ProjectID now part of authentication
+
+2.5.0 (June 3, 2011)
+====================
+
+* better logging thanks to GridDynamics
+
+2.4.4 (June 1, 2011)
+====================
+
+* added support for GET /servers with reservation_id (and /servers/detail)
+
+2.4.3 (May 27, 2011)
+====================
+
+* added support for POST /zones/select (client only, not cmdline)
+
+2.4 (March 7, 2011)
+===================
+
+* added Jacob Kaplan-Moss copyright notices to older/untouched files.
+
+
+2.3 (March 2, 2011)
+===================
+
+* package renamed to python-novaclient. Module to novaclient
+
+
+2.2 (March 1, 2011)
+===================
+
+* removed some license/copywrite notices from source that wasn't
+  significantly changed.
+
+
+2.1 (Feb 28, 2011)
+==================
+
+* shell renamed to nova from novatools
+
+* license changed from BSD to Apache
+
+2.0 (Feb 7, 2011)
+=================
+
+* Forked from https://github.com/jacobian/python-cloudservers
+
+* Rebranded to python-novatools
+
+* Auth URL support
+
+* New OpenStack specific commands added (pause, suspend, etc)
+
+1.2 (August 15, 2010)
+=====================
+
+* Support for Python 2.4 - 2.7.
+
+* Improved output of :program:`cloudservers ipgroup-list`.
+
+* Made ``cloudservers boot --ipgroup <name>`` work (as well as ``--ipgroup
+  <id>``).
+
+1.1 (May 6, 2010)
+=================
+
+* Added a ``--files`` option to :program:`cloudservers boot` supporting
+  the upload of (up to five) files at boot time.
+
+* Added a ``--key`` option to :program:`cloudservers boot` to key the server
+  with an SSH public key at boot time. This is just a shortcut for ``--files``,
+  but it's a useful shortcut.
+
+* Changed the default server image to Ubuntu 10.04 LTS.
diff --git a/doc/source/shell.rst b/doc/source/shell.rst
new file mode 100644
index 0000000..c44d6b3
--- /dev/null
+++ b/doc/source/shell.rst
@@ -0,0 +1,59 @@
+The :program:`keystone` shell utility
+=========================================
+
+.. program:: keystone
+.. highlight:: bash
+
+
+The :program:`keystone` shell utility interacts with OpenStack Keystone API
+from the command line. It supports the entirety of the OpenStack Keystone API.
+
+First, you'll need an OpenStack Keystone account. You get this by using the 
+`keystone-manage` command in OpenStack Keystone.
+
+You'll need to provide :program:`keystone` with your OpenStack username and
+password. You can do this with the :option:`--os_username`, :option:`--os_password`.
+You can optionally specify a :option:`--os_tenant_id` or :option:`--os_tenant_name`,
+to scope your token to a specific tenant.  If you don't specify a tenant, you
+will be scoped to your default tenant if you have one.  Instead of using 
+options, it is easier to just set them as environment variables:
+
+.. envvar:: OS_USERNAME
+
+    Your Keystone username.
+
+.. envvar:: OS_PASSWORD
+
+    Your Keystone password.
+
+.. envvar:: OS_TENANT_NAME
+
+    Name of Keystone Tenant.
+
+.. envvar:: OS_TENANT_ID
+
+    ID of Keystone Tenant.
+
+.. envvar:: OS_AUTH_URL
+
+    The OpenStack API server URL.
+
+.. envvar:: OS_IDENTITY_API_VERSION
+
+    The OpenStack Identity API version.
+
+For example, in Bash you'd use::
+
+    export OS_USERNAME=yourname
+    export OS_PASSWORD=yadayadayada
+    export OS_TENANT_NAME=myproject
+    export OS_AUTH_URL=http://example.com:5000/v2.0/
+    export OS_IDENTITY_API_VERSION=2.0
+
+From there, all shell commands take the form::
+
+    keystone <command> [arguments...]
+
+Run :program:`keystone help` to get a full list of all possible commands,
+and run :program:`keystone help <command>` to get detailed help for that
+command.
diff --git a/doc/source/using-api.rst b/doc/source/using-api.rst
new file mode 100644
index 0000000..d8fa0bc
--- /dev/null
+++ b/doc/source/using-api.rst
@@ -0,0 +1,109 @@
+==============
+The client API
+==============
+
+Introduction
+============
+The main concepts in the Keystone API are:
+
+ * tenants
+ * users
+ * roles
+ * services
+ * endpoints
+
+The Keystone API lets you query and make changes through managers. For example,
+to maipulate tenants, you interact with a
+``keystoneclient.v2_0.tenants.TenantManger`` object.
+
+You obtain access to managers through via atributes of the ``keystoneclient.v2_0.client.Client`` object. For example, the ``tenants`` attribute of the ``Client``
+class is a tenant manager::
+
+    >>> from keystoneclient.v2_0 import client
+    >>> keystone = client.Client(...)
+    >>> keystone.tenants.list() # List tenants
+
+You create a valid ``keystoneclient.v2_0.client.Client`` object by passing
+authentication data to the constructor. Authentication and examples of common
+tasks are provided below.
+
+Authenticating
+==============
+
+There are two ways to authenticate against Keystone:
+ * against the admin endpoint with the admin token
+ * against the public endpoint with a username and password
+
+If you are an administrator, you can authenticate by connecting to the admin
+endpoint and using the admin token (sometimes referred to as the service
+token). The token is specified as the ``admin_token`` configuration option in your
+keystone.conf config file, which is typically in /etc/keystone::
+
+    >>> from keystoneclient.v2_0 import client
+    >>> token = '012345SECRET99TOKEN012345'
+    >>> endpoint = 'http://192.168.206.130:35357/v2.0'
+    >>> keystone = client.Client(token=token, endpoint=endpoint)
+
+If you have a username and password, authentication is done against the
+public endpoint. You must also specify a tenant that is associated with the
+user::
+
+    >>> from keystoneclient.v2_0 import client
+    >>> username='adminUser'
+    >>> password='secreetword'
+    >>> tenant_name='openstackDemo'
+    >>> auth_url='http://192.168.206.130:5000/v2.0'
+    >>> keystone = client.Client(username=username, password=password,
+    ...                         tenant_name, auth_url=auth_url)
+
+Creating tenants
+================
+
+This example will create a tenant named *openStackDemo*::
+
+    >>> from keystoneclient.v2_0 import client
+    >>> keystone = client.Client(...)
+    >>> keystone.tenants.create(tenant_name="openstackDemo",
+    ...                         description="Default Tenant", enabled=True)
+    <Tenant {u'id': u'9b7962da6eb04745b477ae920ad55939', u'enabled': True, u'description': u'Default Tenant', u'name': u'openstackDemo'}>
+
+Creating users
+==============
+
+This example will create a user named *adminUser* with a password *secretword*
+in the opoenstackDemo tenant. We first need to retrieve the tenant::
+
+    >>> from keystoneclient.v2_0 import client
+    >>> keystone = client.Client(...)
+    >>> tenants = keystone.tenants.list()
+    >>> my_tenant = [x for x in tenants if x.name=='openstackDemo'][0]
+    >>> my_user = keystone.users.create(name="adminUser", password="secretword",
+    ...                                                   tenant_id=my_tenant.id)
+
+Creating roles and adding users
+===============================
+
+This example will create an admin role and add the *my_user* user to that
+role, but only for the *my_tenant* tenant:
+
+    >>> from keystoneclient.v2_0 import client
+    >>> keystone = client.Client(...)
+    >>> role = keystone.roles.create('admin')
+    >>> my_tenant = ...
+    >>> my_user = ...
+    >>> keystone.roles.add_user_role(my_user, role, my_tenant)
+
+Creating services and endpoints
+===============================
+
+This example will create the service and corresponding endpoint for the
+Compute service::
+
+    >>> from keystoneclient.v2_0 import client
+    >>> keystone = client.Client(...)
+    >>> service = keystone.services.create(name="nova", service_type="compute",
+    ...                                    description="Nova Compute Service")
+    >>> keystone.endpoints.create(region="RegionOne", service_id=service.id,
+    ...            publicurl="http://192.168.206.130:8774/v2/%(tenant_id)s",
+    ...            adminurl="http://192.168.206.130:8774/v2/%(tenant_id)s",
+    ...            internalurl="http://192.168.206.130:8774/v2/%(tenant_id)s")