updating docs:

* reference keystone-all instead of keystone
* remove reference to keystone.version
* rename gnerated man page
* spacing and line wrapping

7 files changed, 190 insertions, 65 deletions

diff --git a/docs/source/conf.py b/docs/source/conf.py
index edae0b8a..fc7d9476 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -52,7 +52,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'keystone'
-copyright = u'2012, termie'
+copyright = u'2012, OpenStack, LLC'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -105,7 +105,7 @@ modindex_common_prefix = ['keystone.']
 man_pages = [
     ('man/keystone-manage', 'keystone-manage', u'Keystone Management Utility',
      [u'OpenStack'], 1),
-    ('man/keystone', 'keystone', u'Keystone Startup Command',
+    ('man/keystone-all', 'keystone-all', u'Keystone Startup Command',
      [u'OpenStack'], 1),
  ]
 
@@ -207,8 +207,8 @@ latex_elements = {
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'keystone.tex', u'keystone Documentation',
-   u'termie', 'manual'),
+  ('index', 'keystone.tex', u'Keystone Documentation',
+   u'OpenStack', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -237,8 +237,8 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'keystone', u'keystone Documentation',
-     [u'termie'], 1)
+    ('index', 'keystone', u'Keystone Documentation',
+     [u'OpenStack'], 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -251,8 +251,8 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'keystone', u'keystone Documentation',
-   u'termie', 'keystone', 'One line description of project.',
+  ('index', 'keystone', u'Keystone Documentation',
+   u'OpenStack', 'keystone', 'One line description of project.',
    'Miscellaneous'),
 ]
 
diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
index 782e9fb5..7fbcf026 100644
--- a/docs/source/configuration.rst
+++ b/docs/source/configuration.rst
@@ -22,6 +22,7 @@ Configuring Keystone
    :maxdepth: 1
 
    man/keystone-manage
+   man/keystone-all
 
 Once Keystone is installed, it is configured via a primary configuration file
 (``etc/keystone.conf``), possibly a separate logging configuration file, and
@@ -34,15 +35,14 @@ Keystone Configuration File
 The keystone configuration file is an 'ini' file format with sections,
 extended from Paste_, a common system used to configure python WSGI based
 applications. In addition to the paste config entries, general configuration
-values are stored under [DEFAULT] and [sql], and then drivers for the various
-backend components are included under their individual sections.
+values are stored under ``[DEFAULT]``, ``[sql]``, ``[ec2]`` and then drivers
+for the various services are included under their individual sections.
 
-The driver sections include:
+The services include:
 * ``[identity]`` - the python module that backends the identity system
 * ``[catalog]`` - the python module that backends the service catalog
 * ``[token]`` - the python module that backends the token providing mechanisms
 * ``[policy]`` - the python module that drives the policy system for RBAC
-* ``[ec2]`` - the python module providing the EC2 translations for OpenStack
 
 The keystone configuration file is expected to be named ``keystone.conf``.
 When starting up Keystone, you can specify a different configuration file to
@@ -61,7 +61,8 @@ file under ``log_config``. If you wish to route all your logging through
 syslog, there is a ``use_syslog`` option also in the [DEFAULT] section that
 easy.
 
-A sample logging file is available with the project in the directory ``etc/logging.conf.sample``. Like other OpenStack projects, keystone uses the
+A sample logging file is available with the project in the directory
+``etc/logging.conf.sample``. Like other OpenStack projects, keystone uses the
 `python logging module`, which includes extensive configuration options for
 choosing the output levels and formats.
 
@@ -78,6 +79,18 @@ Sample Configuration Files
 * ``etc/keystone.conf``
 * ``etc/logging.conf.sample``
 
+Running Keystone
+================
+
+Running keystone is simply starting the services by using the command::
+
+    keystone-all
+
+Invoking this command starts up two wsgi.Server instances, configured by the
+``keystone.conf`` file as described above. One of these wsgi 'servers' is
+``admin`` (the administration API) and the other is ``main`` (the
+primary/public  API interface). Both of these run in a single process.
+
 Initializing Keystone
 =====================
 
@@ -129,7 +142,8 @@ containers within Swift. A tenant can have zero or more users, Users can be asso
 keyword arguments
 
 * tenant_name
-* id (optional)
+* description (optional, defaults to None)
+* enabled (optional, defaults to True)
 
 example::
 
@@ -142,7 +156,7 @@ creates a tenant named "admin".
 
 keyword arguments
 
-* tenant_id
+* tenant
 
 example::
 
@@ -153,9 +167,10 @@ example::
 
 keyword arguments
 
-* description
-* name
 * tenant_id
+* tenant_name (optional, defaults to None)
+* description (optional, defaults to None)
+* enabled (optional, defaults to True)
 
 example::
 
@@ -175,6 +190,8 @@ keyword arguments
 * name
 * password
 * email
+* tenant_id (optional, defaults to None)
+* enabled (optional, defaults to True)
 
 example::
 
@@ -188,31 +205,56 @@ example::
 
 keyword arguments
 
+* user
+
+example::
+
+	keystone-manage user --ks-id-only delete f2b7b39c860840dfa47d9ee4adffa0b3
+
 ``user list``
 ^^^^^^^^^^^^^
 
+list users in the system, optionally by a specific tenant (identified by tenant_id)
+
 keyword arguments
 
+* tenant_id (optional, defaults to None)
+* limit (optional, defaults to None)
+* marker (optional, defaults to None)
+
 ``user update_email``
 ^^^^^^^^^^^^^^^^^^^^^
 
 keyword arguments
 
+* user
+* email
+
 ``user update_enabled``
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 keyword arguments
 
+* user
+* enabled (True or False)
+
 ``user update_password``
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 keyword arguments
 
+* user
+* password
+
 ``user update_tenant``
 ^^^^^^^^^^^^^^^^^^^^^^
 
 keyword arguments
 
+* user
+* tenant
+
+
 Roles
 -----
 
@@ -227,27 +269,67 @@ exmaple::
 
 	keystone-manage role --ks-id-only create name=Admin
 
-``role add_user_to_tenant``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``role delete``
+^^^^^^^^^^^^^^^
 
 keyword arguments
 
-* role_id
-* user_id
-* tenant_id
+* role
+
+exmaple::
+
+	keystone-manage role delete role=19d1d3344873464d819c45f521ff9890
+
+``role list``
+^^^^^^^^^^^^^^^
+
+exmaple::
+
+	keystone-manage role list
+
+``role add_user_role``
+^^^^^^^^^^^^^^^^^^^^^^
+
+keyword arguments
+
+* role
+* user
+* tenant (optional, defaults to None)
 
 example::
 
-	keystone-manage role add_user_to_tenant \
-	role_id=19d1d3344873464d819c45f521ff9890 \
-	user_id=08741d8ed88242ca88d1f61484a0fe3b \
-	tenant_id=20601a7f1d94447daa4dff438cb1c209
+	keystone-manage role add_user_role \
+	role=19d1d3344873464d819c45f521ff9890 \
+	user=08741d8ed88242ca88d1f61484a0fe3b \
+	tenant=20601a7f1d94447daa4dff438cb1c209
 
-``role remove_user_from_tenant``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``role remove_user_role``
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
-``role get_user_role_refs``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+keyword arguments
+
+* role
+* user
+* tenant (optional, defaults to None)
+
+example::
+
+	keystone-manage role remove_user_to_tenant \
+	role=19d1d3344873464d819c45f521ff9890 \
+	user=08741d8ed88242ca88d1f61484a0fe3b \
+	tenant=20601a7f1d94447daa4dff438cb1c209
+
+``role roles_for_user``
+^^^^^^^^^^^^^^^^^^^^^^^
+
+keyword arguments
+
+* user
+* tenant (optional, defaults to None)
+
+example::
+
+	keystone-manage role roles_for_user user=08741d8ed88242ca88d1f61484a0fe3b
 
 Services
 --------
@@ -267,3 +349,31 @@ example::
     name=nova \
     service_type=compute \
     description="Nova Compute Service"
+
+``service list``
+^^^^^^^^^^^^^^^^
+
+keyword arguments
+
+example::
+
+	keystone-manage service list
+
+``service get``
+^^^^^^^^^^^^^^^
+
+keyword arguments
+
+example::
+
+	keystone-manage service get id=08741d8ed88242ca88d1f61484a0fe3b
+
+``service delete``
+^^^^^^^^^^^^^^^^^^
+
+keyword arguments
+
+example::
+
+	keystone-manage service delete id=08741d8ed88242ca88d1f61484a0fe3b
+
diff --git a/docs/source/configuringservices.rst b/docs/source/configuringservices.rst
index 88bb9c15..5ea75461 100644
--- a/docs/source/configuringservices.rst
+++ b/docs/source/configuringservices.rst
@@ -24,12 +24,14 @@ Configuring Services to work with Keystone
     nova-api-paste
     middleware_architecture
 
-Once Keystone is installed and running (see :doc:`configuration`), services need to be configured to work
-with it. To do this, we primarily install and configure middleware for the OpenStack service to handle authentication tasks or otherwise interact with Keystone.
+Once Keystone is installed and running (see :doc:`configuration`), services
+need to be configured to work with it. To do this, we primarily install and
+configure middleware for the OpenStack service to handle authentication tasks
+or otherwise interact with Keystone.
 
 In general:
-* Clients making calls to the service will pass in an authentication token. 
-* The Keystone middleware will look for and validate that token, taking the appropriate action. 
+* Clients making calls to the service will pass in an authentication token.
+* The Keystone middleware will look for and validate that token, taking the appropriate action.
 * It will also retrive additional information from the token such as user name, id, tenant name, id, roles, etc...
 
 The middleware will pass those data down to the service as headers. More details on the architecture of
@@ -42,13 +44,16 @@ Admin Token
 -----------
 
 For a default installation of Keystone, before you can use the REST API, you
-need to define an authorization token. This is configured in the keystone.conf file under the section ``[DEFAULT]``. In the sample file provided with the keystone project, the line defining this token is
+need to define an authorization token. This is configured in ``keystone.conf``
+file under the section ``[DEFAULT]``. In the sample file provided with the keystone project, the line defining this token is
 
 	[DEFAULT]
 	admin_token = ADMIN
 
-This is a "shared secret" between keystone and other openstack services, and will need to be set the
-same between those services in order for keystone services to function correctly.
+This configured token is a "shared secret" between keystone and other
+openstack services (for example: nova, swift, glance, or horizon), and will
+need to be set the same between those services in order for keystone services
+to function correctly.
 
 Setting up tenants, users, and roles
 ------------------------------------
@@ -58,7 +63,7 @@ You need to minimally define a tenant, user, and role to link the tenant and use
 Setting up services
 ===================
 
-Defining Services 
+Defining Services
 -----------------
 
 Keystone also acts as a service catalog to let other OpenStack systems know
@@ -146,7 +151,7 @@ rather than it's built in 'tempauth'.
 
    Note that the optional "cache" property in the keystone filter allows any
    service (not just Swift) to register its memcache client in the WSGI
-   environment.  If such a cache exists, Keystone middleware will utilize it 
+   environment.  If such a cache exists, Keystone middleware will utilize it
    to store validated token information, which could result in better overall
    performance.
 
diff --git a/docs/source/developing.rst b/docs/source/developing.rst
index f529761e..f7c0b87b 100644
--- a/docs/source/developing.rst
+++ b/docs/source/developing.rst
@@ -22,7 +22,7 @@ Contributing Code
 =================
 
 To contribute code, sign up for a Launchpad account and sign a contributor license agreement,
-available on the `<http://wiki.openstack.org/CLA>`_. Once the CLA is signed you 
+available on the `<http://wiki.openstack.org/CLA>`_. Once the CLA is signed you
 can contribute code through the Gerrit version control system which is related to your Launchpad account.
 
 To contribute tests, docs, code, etc, refer to our `Gerrit-Jenkins-Github Workflow`_.
@@ -40,8 +40,8 @@ Running Keystone
 
 To run the keystone Admin and API server instances, use::
 
-    $ tools/with_venv.sh bin/keystone
-	
+    $ tools/with_venv.sh bin/keystone-all
+
 this runs keystone with the configuration the etc/ directory of the project. See :doc:`configuration` for details on how Keystone is configured.
 
 Interacting with Keystone
@@ -76,20 +76,32 @@ light integration testing to verify the keystone API against other projects.
 Test Structure
 --------------
 
-``./run_test.sh`` uses it's python cohort (``run_tests.py``) to iterate through the ``tests`` directory, using Nosetest to collect the tests and invoke them using an 
-OpenStack custom test running that displays the tests as well as the time taken to
+``./run_test.sh`` uses its python cohort (``run_tests.py``) to iterate
+through the ``tests`` directory, using Nosetest to collect the tests and
+invoke them using an OpenStack custom test running that displays the tests
+as well as the time taken to
 run those tests.
 
-Within the tests directory, the general structure of the tests is a basic set of tests represented under a test class, and then subclasses of those tests under other classes with different configurations to drive different backends through the APIs.
+Within the tests directory, the general structure of the tests is a basic
+set of tests represented under a test class, and then subclasses of those
+tests under other classes with different configurations to drive different
+backends through the APIs.
 
-For example, ``test_backend.py`` has a sequence of tests under the class ``IdentityTests`` that will work with the default drivers as configured in this projects etc/ directory. ``test_backend_sql.py`` subclasses those tests, changing the configuration by overriding with configuration files stored in the tests directory aimed at enabling the SQL backend for the Identity module.
+For example, ``test_backend.py`` has a sequence of tests under the class
+``IdentityTests`` that will work with the default drivers as configured in
+this projects etc/ directory. ``test_backend_sql.py`` subclasses those tests,
+changing the configuration by overriding with configuration files stored in
+the tests directory aimed at enabling the SQL backend for the Identity module.
 
-Likewise, ``test_cli.py`` takes advantage of the tests written aainst ``test_keystoneclient`` to verify the same tests function through different drivers.
+Likewise, ``test_cli.py`` takes advantage of the tests written aainst
+``test_keystoneclient`` to verify the same tests function through different
+drivers.
 
 Testing Schema Migrations
 -------------------------
 
-The application of schema migrations can be tested using SQLAlchemy Migrate’s built-in test runner, one migration at a time.
+The application of schema migrations can be tested using SQLAlchemy Migrate’s
+built-in test runner, one migration at a time.
 
 .. WARNING::
 
diff --git a/docs/source/man/keystone.rst b/docs/source/man/keystone-all.rst
index 74d0bb69..66d0ee4e 100644
--- a/docs/source/man/keystone.rst
+++ b/docs/source/man/keystone-all.rst
@@ -16,17 +16,19 @@ Keystone Management Utility
 SYNOPSIS
 ========
 
-  keystone [options]
+  keystone-all [options]
 
 DESCRIPTION
 ===========
 
-keystone starts both the service and administrative APIs for Keystone.
+keystone-all starts both the service and administrative APIs in a single
+process to provide catalog, authorization, and authentication services for
+OpenStack.
 
 USAGE
 =====
 
- keystone ``keystone [options]``
+    ``keystone-all [options]``
 
 Common Options:
 ^^^^^^^^^^^^^^^
@@ -63,7 +65,7 @@ programs.::
                         syslog (defaults to LOG_USER)
   --use-syslog          Use syslog for logging.
   --nouse-syslog        Use syslog for logging.
-  
+
 FILES
 =====
 
@@ -77,5 +79,5 @@ SEE ALSO
 SOURCE
 ======
 
-* Keystone is sourced in GitHub `Keystone <http://github.com/openstack/keystone>`__
+* Keystone source in managed in GitHub `Keystone <http://github.com/openstack/keystone>`__
 * Keystone bugs are managed at Launchpad `Launchpad Keystone <https://bugs.launchpad.net/keystone>`__
diff --git a/docs/source/nova-api-paste.rst b/docs/source/nova-api-paste.rst
index 586bac72..602895ac 100644
--- a/docs/source/nova-api-paste.rst
+++ b/docs/source/nova-api-paste.rst
@@ -136,7 +136,8 @@ nova-api-paste example
     auth_host = 127.0.0.1
     auth_port = 35357
     auth_protocol = http
-    auth_uri = http://127.0.0.1:5000/
+    auth_uri = http://your_keystone_host.com:5000/
+    ;identical to the admin token defined in keystone.conf
     admin_token = 999888777666
     ;Uncomment next line and check ip:port to use memcached to cache token requests
     ;memcache_hosts = 127.0.0.1:11211
diff --git a/docs/source/setup.rst b/docs/source/setup.rst
index 4f6b6137..7d03fd66 100644
--- a/docs/source/setup.rst
+++ b/docs/source/setup.rst
@@ -62,10 +62,10 @@ When that is complete, you can::
 Installing dependencies
 =======================
 
-Keystone maintains two lists of dependencies:
+Keystone maintains two lists of dependencies::
 
     tools/pip-requires
-	tools/pip-requires-test
+    tools/pip-requires-test
 
 The first is the list of dependencies needed for running keystone, the second list includes dependencies used for active development and testing of keystone itself.
 
@@ -97,7 +97,7 @@ PyPi Packages and VirtualEnv
 ----------------------------
 
 We recommend establishing a virtualenv to run keystone within. Virtualenv limits the python environment
-to just what you're installing as depdendencies, useful to keep a clean environment for working on 
+to just what you're installing as depdendencies, useful to keep a clean environment for working on
 Keystone. The tools directory in keystone has a script already created to make this very simple::
 
     $ python tools/install_venv.py
@@ -125,10 +125,10 @@ into your system from the requires files::
 
     # Install the dependencies for developing, testing, and running keystone
     $ pip install -r tools/pip-requires-test
-	
+
     # Fake-install the project by symlinking Keystone into your Python site-packages
     $ python setup.py develop
-	
+
 
 Verifying Keystone is set up
 ============================
@@ -142,14 +142,9 @@ the libraries. If you're using a virtualenv, don't forget to activate it::
 You should then be able to `import keystone` from your Python shell
 without issue::
 
-    >>> import keystone.version
+    >>> import keystone
     >>>
 
-If you want to check the version of Keystone you are running:
-
-    >>> print keystone.version.version()
-    2012.1-dev
-
 If you can import keystone successfully, you should be ready to move on to :doc:`developing`
 
 Troubleshooting