Fixed multiple warnings in tox -edocs

There are multiple tracebacks and warnings being thrown whenever
the keystone docs are built due to documents being moved/deleted as
well as formatting issues in a couple places.

This fixes a few of the warnings due to broken links and fixes a few
of the method docs.

Master: http://paste.openstack.org/show/591730/
This Patch: http://paste.openstack.org/show/591735/

Change-Id: I11cbbc7a10fa24dcbf67c76e3061a39a58529c06
Partial-Bug: #1602422

doc/source/devref/development.environment.rst

@@ -76,4 +76,4 @@ Once set up, you should be able to invoke Python and import the libraries:
     $ .tox/py27/bin/python -c "import keystone"
 
 If you can import keystone without a traceback, you should be ready to move on
-to :doc:`../developing`.
+to :doc:`development_best_practices`.

doc/source/devref/development_best_practices.rst

@@ -22,7 +22,7 @@ Setting up Keystone
 ===================
 
 Get your development environment set up according to
-:doc:`devref/development.environment`. It is recommended that you install
+:doc:`development.environment`. It is recommended that you install
 Keystone into a virtualenv.
 
 
@@ -50,7 +50,7 @@ To run the Keystone Admin and API server instances, use:
     $ uwsgi --http 127.0.0.1:35357 --wsgi-file $(which keystone-wsgi-admin)
 
 This runs Keystone with the configuration the etc/ directory of the project.
-See :doc:`configuration` for details on how Keystone is configured. By default,
+See :doc:`../configuration` for details on how Keystone is configured. By default,
 Keystone is configured with SQL backends.
 
 
@@ -204,7 +204,7 @@ Running Tests
 
 Before running tests, you should have ``tox`` installed and available in your
 environment (in addition to the other external dependencies in
-:doc:`devref/development.environment`):
+:doc:`development.environment`):
 
 .. code-block:: bash
 

doc/source/federation/shibboleth.rst

@@ -102,7 +102,7 @@ file. You will want to change five settings:
     <ApplicationDefaults entityID="http://mysp.example.com/shibboleth">
 
 * Set the IdP entity ID. This value is determined by the IdP. For example, if
-Keystone is the IdP:
+  Keystone is the IdP:
 
 .. code-block:: xml
 

doc/source/installing.rst

@@ -20,7 +20,8 @@ Installing Keystone
 ===================
 
 This document describes how to install Keystone in order to use it. If you are
-intending to develop on or with Keystone, please read :doc:`developing` and
+intending to develop on or with Keystone, please read
+:doc:`devref/development_best_practices` and
 :doc:`devref/development.environment`.
 
 Installing from Source
@@ -82,7 +83,7 @@ the command:
 
 By default, this will show logging on the console from which it was started.
 Once started, you can initialize data in Keystone for use with the rest of
-OpenStack, as described in :doc:`configuringservices`.
+OpenStack, as described in :doc:`configuration`.
 
 An excellent reference implementation of setting up Keystone is DEVSTACK_,
 most commonly used for development and testing setup of not only Keystone,
@@ -110,7 +111,7 @@ the Keystone service (`keystone`), and place default configurations in
 all SQL based, stored locally in SQLite.
 
 Once installed, you still need to initialize data in Keystone, which you can
-find described in :doc:`configuringservices`.
+find described in :doc:`configuration`.
 
 Installing from packages: Fedora
 --------------------------------
@@ -125,6 +126,6 @@ To install the packages:
     $ sudo yum install openstack-keystone
 
 Once installed, you still need to initialize data in Keystone, which you can
-find described in :doc:`configuringservices`.
+find described in :doc:`configuration`.
 
 .. _`OpenStack Install Guide`: http://docs.openstack.org/liberty/install-guide-rdo/keystone-install.html

keystone/common/utils.py

@@ -491,14 +491,16 @@ def isotime(at=None, subsecond=False):
     Python provides a similar instance method for datetime.datetime objects
     called `isoformat()`. The format of the strings generated by `isoformat()`
     has a couple of problems:
+
     1) The strings generated by `isotime()` are used in tokens and other public
-       APIs that we can't change without a deprecation period. The strings
-       generated by `isoformat()` are not the same format, so we can't just
-       change to it.
+    APIs that we can't change without a deprecation period. The strings
+    generated by `isoformat()` are not the same format, so we can't just
+    change to it.
+
     2) The strings generated by `isoformat()` do not include the microseconds
-       if the value happens to be 0. This will likely show up as random
-       failures as parsers may be written to always expect microseconds, and it
-       will parse correctly most of the time.
+    if the value happens to be 0. This will likely show up as random
+    failures as parsers may be written to always expect microseconds, and it
+    will parse correctly most of the time.
 
     :param at: Optional datetime object to return at a string. If not provided,
                the time when the function was called will be used.