Correct docstrings

There were several warnings logged when docs were built due to
invalid rst and other issues.

Change-Id: I61289d05377b8e70afbcf8786d4159354aa67ed8

doc/source/developing.rst

@@ -183,7 +183,7 @@ guidelines for schema and data migrations should be followed:
   are filled with null values before removing them.
 
 A good example of an online schema migration is documented in a `cinder spec`_.
-See more examples in :doc:`devref/online_schema_migration_examples`.
+See more examples in :doc:`online_schema_migration_examples`.
 
 .. _`online schema migration`: https://specs.openstack.org/openstack/keystone-specs/specs/mitaka/online-schema-migration.html
 .. _`MySQL docs`: https://dev.mysql.com/doc/refman/5.7/en/innodb-create-index-overview.html

doc/source/index.rst

@@ -84,8 +84,8 @@ Developers Documentation
    apache-httpd
    external-auth
    event_notifications
-   extension_development
    services
+   online_schema_migration_examples
 
 Code Documentation
 ==================

doc/source/installing.rst

@@ -56,7 +56,7 @@ Install the Keystone web service:
     This step is guaranteed to fail if you do not have the proper binary
     dependencies already installed on your development system. Maintaining a
     list of platform-specific dependencies is outside the scope of this
-    documentation, but is within scope of `DevStack <http://devstack.org/>`_.
+    documentation, but is within scope of DEVSTACK_.
 
 You should have all the pieces you need to run Keystone installed on your
 system. The following commands should be available on the command-line path:

keystone/tests/unit/core.py

@@ -849,7 +849,7 @@ class SQLDriverOverrides(object):
         :param driver_path: The path to the drivers, e.g. 'keystone.assignment'
         :param versionless_backend: The name of the versionless drivers, e.g.
                                     'backends'
-        :param version_suffix: The suffix for the version , e.g. 'V8_'
+        :param version_suffix: The suffix for the version , e.g. ``V8_``
 
         This method assumes that versioned drivers are named:
         <version_suffix><name of versionless driver>, e.g. 'V8_backends'.