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/functional/core.py

@@ -53,7 +53,7 @@ class BaseTestCase(testtools.TestCase, common_auth.AuthTestMixin):
         """Convenience method so that we can test authenticated requests
 
         :param user: A dictionary with user information like 'username',
-        'password', 'domain_id'
+                     'password', 'domain_id'
         :returns: urllib3.Response object
 
         """
@@ -70,7 +70,7 @@ class BaseTestCase(testtools.TestCase, common_auth.AuthTestMixin):
         This method doesn't do any token validaton.
 
         :param user: A dictionary with user information like 'username',
-        'password', 'domain_id'
+                     'password', 'domain_id'
         :returns: An OpenStack token for further use
         :rtype: str
 

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'.

keystone/tests/unit/test_v3_protection.py

@@ -574,7 +574,7 @@ class IdentityTestv3CloudPolicySample(test_v3.RestfulTestCase,
           - project_admin_user has role 'admin' on the project,
           - just_a_user has a non-admin role on both domainA and the project.
         - admin_domain has admin_project, and user cloud_admin_user, with an
-        'admin' role on admin_project.
+          'admin' role on admin_project.
 
         We test various api protection rules from the cloud sample policy
         file to make sure the sample is valid and that we correctly enforce it.

keystone/tests/unit/test_v3_resource.py

@@ -83,7 +83,7 @@ class ResourceTestCase(test_v3.RestfulTestCase,
                 expected_status=http_client.BAD_REQUEST)
 
     def test_create_domain_unsafe_default(self):
-        """Check default for unsafe names for``POST /domains ``."""
+        """Check default for unsafe names for ``POST /domains``."""
         unsafe_name = 'i am not / safe'
 
         # By default, we should be able to create unsafe names
@@ -138,7 +138,7 @@ class ResourceTestCase(test_v3.RestfulTestCase,
                 expected_status=http_client.BAD_REQUEST)
 
     def test_update_domain_unsafe_default(self):
-        """Check default for unsafe names for``POST /domains ``."""
+        """Check default for unsafe names for ``POST /domains``."""
         unsafe_name = 'i am not / safe'
 
         # By default, we should be able to create unsafe names
@@ -505,7 +505,7 @@ class ResourceTestCase(test_v3.RestfulTestCase,
                 expected_status=http_client.BAD_REQUEST)
 
     def test_create_project_unsafe_default(self):
-        """Check default for unsafe names for``POST /projects ``."""
+        """Check default for unsafe names for ``POST /projects``."""
         unsafe_name = 'i am not / safe'
 
         # By default, we should be able to create unsafe names
@@ -1020,7 +1020,7 @@ class ResourceTestCase(test_v3.RestfulTestCase,
                 expected_status=http_client.BAD_REQUEST)
 
     def test_update_project_unsafe_default(self):
-        """Check default for unsafe names for``POST /projects ``."""
+        """Check default for unsafe names for ``POST /projects``."""
         unsafe_name = 'i am not / safe'
 
         # By default, we should be able to create unsafe names