fix restructuredtext formatting in docstrings that show up in the developer guide

blueprint sphinx-doc-cleanup
bug 945160

- Correct parameter declarations, list formatting, cross-references, etc.
- We don't need "let" in generate_autodoc_index.sh since we aren't doing math.
- Change conf.py to not prefix class and function names with full namespace
  in generated output to save width on the screen.

Change-Id: I9adc8681951913fd291d03e7142146e9d46841df

2 files changed, 93 insertions, 87 deletions

diff --git a/nova/auth/fakeldap.py b/nova/auth/fakeldap.py
index d092e7e42..82c6816a0 100644
--- a/nova/auth/fakeldap.py
+++ b/nova/auth/fakeldap.py
@@ -244,9 +244,9 @@ class FakeLDAP(object):
     def modify_s(self, dn, attrs):
         """Modify the object at dn using the attribute list.
 
-        Args:
-        dn -- a dn
-        attrs -- a list of tuples in the following form:
+        :param dn: a dn
+        :param attrs: a list of tuples in the following form::
+
             ([MOD_ADD | MOD_DELETE | MOD_REPACE], attribute, value)
 
         """
diff --git a/nova/auth/manager.py b/nova/auth/manager.py
index 23d9cee05..73994dc3d 100644
--- a/nova/auth/manager.py
+++ b/nova/auth/manager.py
@@ -129,11 +129,17 @@ class User(AuthBase):
     """Object representing a user
 
     The following attributes are defined:
-    :id:       A system identifier for the user.  A string (for LDAP)
-    :name:     The user name, potentially in some more friendly format
-    :access:   The 'username' for EC2 authentication
-    :secret:   The 'password' for EC2 authenticatoin
-    :admin:    ???
+
+    ``id``
+      A system identifier for the user.  A string (for LDAP)
+    ``name``
+      The user name, potentially in some more friendly format
+    ``access``
+      The 'username' for EC2 authentication
+    ``secret``
+      The 'password' for EC2 authenticatoin
+    ``admin``
+      ???
     """
 
     def __init__(self, id, name, access, secret, admin):
@@ -259,35 +265,35 @@ class AuthManager(object):
         a project with the same name as the user. This way, older tools
         that have no project knowledge will still work.
 
-        @type access: str
-        @param access: Access key for user in the form "access:project".
+        :type access: str
+        :param access: Access key for user in the form "access:project".
 
-        @type signature: str
-        @param signature: Signature of the request.
+        :type signature: str
+        :param signature: Signature of the request.
 
-        @type params: list of str
-        @param params: Web paramaters used for the signature.
+        :type params: list of str
+        :param params: Web paramaters used for the signature.
 
-        @type verb: str
-        @param verb: Web request verb ('GET' or 'POST').
+        :type verb: str
+        :param verb: Web request verb ('GET' or 'POST').
 
-        @type server_string: str
-        @param server_string: Web request server string.
+        :type server_string: str
+        :param server_string: Web request server string.
 
-        @type path: str
-        @param path: Web request path.
+        :type path: str
+        :param path: Web request path.
 
-        @type check_type: str
-        @param check_type: Type of signature to check. 'ec2' for EC2, 's3' for
+        :type check_type: str
+        :param check_type: Type of signature to check. 'ec2' for EC2, 's3' for
                            S3. Any other value will cause signature not to be
                            checked.
 
-        @type headers: list
-        @param headers: HTTP headers passed with the request (only needed for
+        :type headers: list
+        :param headers: HTTP headers passed with the request (only needed for
                         s3 signature checks)
 
-        @rtype: tuple (User, Project)
-        @return: User and project that the request represents.
+        :rtype: tuple (User, Project)
+        :return: User and project that the request represents.
         """
         # TODO(vish): check for valid timestamp
         (access_key, _sep, project_id) = access.partition(':')
@@ -365,11 +371,11 @@ class AuthManager(object):
     def is_superuser(self, user):
         """Checks for superuser status, allowing user to bypass authorization
 
-        @type user: User or uid
-        @param user: User to check.
+        :type user: User or uid
+        :param user: User to check.
 
-        @rtype: bool
-        @return: True for superuser.
+        :rtype: bool
+        :return: True for superuser.
         """
         if not isinstance(user, User):
             user = self.get_user(user)
@@ -383,11 +389,11 @@ class AuthManager(object):
     def is_admin(self, user):
         """Checks for admin status, allowing user to access all projects
 
-        @type user: User or uid
-        @param user: User to check.
+        :type user: User or uid
+        :param user: User to check.
 
-        @rtype: bool
-        @return: True for admin.
+        :rtype: bool
+        :return: True for admin.
         """
         if not isinstance(user, User):
             user = self.get_user(user)
@@ -429,17 +435,17 @@ class AuthManager(object):
         see if the user is the project_manager of the specified project. It
         is the same as calling is_project_manager(user, project).
 
-        @type user: User or uid
-        @param user: User to check.
+        :type user: User or uid
+        :param user: User to check.
 
-        @type role: str
-        @param role: Role to check.
+        :type role: str
+        :param role: Role to check.
 
-        @type project: Project or project_id
-        @param project: Project in which to look for local role.
+        :type project: Project or project_id
+        :param project: Project in which to look for local role.
 
-        @rtype: bool
-        @return: True if the user has the role.
+        :rtype: bool
+        :return: True if the user has the role.
         """
         if role == 'projectmanager':
             if not project:
@@ -468,14 +474,14 @@ class AuthManager(object):
 
         The 'projectmanager' role is special and can't be added or removed.
 
-        @type user: User or uid
-        @param user: User to which to add role.
+        :type user: User or uid
+        :param user: User to which to add role.
 
-        @type role: str
-        @param role: Role to add.
+        :type role: str
+        :param role: Role to add.
 
-        @type project: Project or project_id
-        @param project: Project in which to add local role.
+        :type project: Project or project_id
+        :param project: Project in which to add local role.
         """
         if role not in FLAGS.allowed_roles:
             raise exception.UserRoleNotFound(role_id=role)
@@ -501,14 +507,14 @@ class AuthManager(object):
 
         The 'projectmanager' role is special and can't be added or removed.
 
-        @type user: User or uid
-        @param user: User from which to remove role.
+        :type user: User or uid
+        :param user: User from which to remove role.
 
-        @type role: str
-        @param role: Role to remove.
+        :type role: str
+        :param role: Role to remove.
 
-        @type project: Project or project_id
-        @param project: Project in which to remove local role.
+        :type project: Project or project_id
+        :param project: Project in which to remove local role.
         """
         uid = User.safe_id(user)
         pid = Project.safe_id(project)
@@ -563,23 +569,23 @@ class AuthManager(object):
                        member_users=None):
         """Create a project
 
-        @type name: str
-        @param name: Name of the project to create. The name will also be
+        :type name: str
+        :param name: Name of the project to create. The name will also be
         used as the project id.
 
-        @type manager_user: User or uid
-        @param manager_user: This user will be the project manager.
+        :type manager_user: User or uid
+        :param manager_user: This user will be the project manager.
 
-        @type description: str
-        @param project: Description of the project. If no description is
+        :type description: str
+        :param project: Description of the project. If no description is
         specified, the name of the project will be used.
 
-        @type member_users: list of User or uid
-        @param: Initial project members. The project manager will always be
+        :type member_users: list of User or uid
+        :param: Initial project members. The project manager will always be
         added as a member, even if he isn't specified in this list.
 
-        @rtype: Project
-        @return: The new project.
+        :rtype: Project
+        :return: The new project.
         """
         if member_users:
             member_users = [User.safe_id(u) for u in member_users]
@@ -597,14 +603,14 @@ class AuthManager(object):
     def modify_project(self, project, manager_user=None, description=None):
         """Modify a project
 
-        @type name: Project or project_id
-        @param project: The project to modify.
+        :type name: Project or project_id
+        :param project: The project to modify.
 
-        @type manager_user: User or uid
-        @param manager_user: This user will be the new project manager.
+        :type manager_user: User or uid
+        :param manager_user: This user will be the new project manager.
 
-        @type description: str
-        @param project: This will be the new description of the project.
+        :type description: str
+        :param project: This will be the new description of the project.
 
         """
         LOG.audit(_("modifying project %s"), Project.safe_id(project))
@@ -648,12 +654,12 @@ class AuthManager(object):
     def get_project_vpn_data(project):
         """Gets vpn ip and port for project
 
-        @type project: Project or project_id
-        @param project: Project from which to get associated vpn data
+        :type project: Project or project_id
+        :param project: Project from which to get associated vpn data
 
-        @rvalue: tuple of (str, str)
-        @return: A tuple containing (ip, port) or None, None if vpn has
-        not been allocated for user.
+        :rvalue: tuple of (str, str)
+        :return: A tuple containing (ip, port) or None, None if vpn has
+                 not been allocated for user.
         """
 
         networks = db.project_get_networks(context.get_admin_context(),
@@ -699,24 +705,24 @@ class AuthManager(object):
     def create_user(self, name, access=None, secret=None, admin=False):
         """Creates a user
 
-        @type name: str
-        @param name: Name of the user to create.
+        :type name: str
+        :param name: Name of the user to create.
 
-        @type access: str
-        @param access: Access Key (defaults to a random uuid)
+        :type access: str
+        :param access: Access Key (defaults to a random uuid)
 
-        @type secret: str
-        @param secret: Secret Key (defaults to a random uuid)
+        :type secret: str
+        :param secret: Secret Key (defaults to a random uuid)
 
-        @type admin: bool
-        @param admin: Whether to set the admin flag. The admin flag gives
+        :type admin: bool
+        :param admin: Whether to set the admin flag. The admin flag gives
         superuser status regardless of roles specified for the user.
 
-        @type create_project: bool
-        @param: Whether to create a project for the user with the same name.
+        :type create_project: bool
+        :param: Whether to create a project for the user with the same name.
 
-        @rtype: User
-        @return: The new user.
+        :rtype: User
+        :return: The new user.
         """
         if access is None:
             access = str(uuid.uuid4())