diff --git a/nova/auth/fakeldap.py b/nova/auth/fakeldap.py
index d092e7e4..82c6816a 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 23d9cee0..73994dc3 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())
diff --git a/nova/common/policy.py b/nova/common/policy.py
index 34492f73..ec944a1c 100644
--- a/nova/common/policy.py
+++ b/nova/common/policy.py
@@ -49,49 +49,64 @@ def enforce(match_list, target_dict, credentials_dict):
     """Enforces authorization of some rules against credentials.
 
     :param match_list: nested tuples of data to match against
-    The basic brain supports three types of match lists:
-        1) rules
-            looks like: ('rule:compute:get_instance',)
-            Retrieves the named rule from the rules dict and recursively
-            checks against the contents of the rule.
-        2) roles
-            looks like: ('role:compute:admin',)
-            Matches if the specified role is in credentials_dict['roles'].
-        3) generic
-            ('tenant_id:%(tenant_id)s',)
-            Substitutes values from the target dict into the match using
-            the % operator and matches them against the creds dict.
 
-    Combining rules:
-        The brain returns True if any of the outer tuple of rules match
-        and also True if all of the inner tuples match. You can use this to
-        perform simple boolean logic.  For example, the following rule would
-        return True if the creds contain the role 'admin' OR the if the
-        tenant_id matches the target dict AND the the creds contains the
-        role 'compute_sysadmin':
+        The basic brain supports three types of match lists:
 
-        {
-            "rule:combined": (
-                'role:admin',
-                ('tenant_id:%(tenant_id)s', 'role:compute_sysadmin')
-            )
-        }
+            1) rules
 
+                looks like: ``('rule:compute:get_instance',)``
 
-    Note that rule and role are reserved words in the credentials match, so
-    you can't match against properties with those names. Custom brains may
-    also add new reserved words. For example, the HttpBrain adds http as a
-    reserved word.
+                Retrieves the named rule from the rules dict and recursively
+                checks against the contents of the rule.
+
+            2) roles
+
+                looks like: ``('role:compute:admin',)``
+
+                Matches if the specified role is in credentials_dict['roles'].
+
+            3) generic
+
+                looks like: ``('tenant_id:%(tenant_id)s',)``
+
+                Substitutes values from the target dict into the match using
+                the % operator and matches them against the creds dict.
+
+        Combining rules:
+
+            The brain returns True if any of the outer tuple of rules
+            match and also True if all of the inner tuples match. You
+            can use this to perform simple boolean logic.  For
+            example, the following rule would return True if the creds
+            contain the role 'admin' OR the if the tenant_id matches
+            the target dict AND the the creds contains the role
+            'compute_sysadmin':
+
+            ::
+
+                {
+                    "rule:combined": (
+                        'role:admin',
+                        ('tenant_id:%(tenant_id)s', 'role:compute_sysadmin')
+                    )
+                }
+
+        Note that rule and role are reserved words in the credentials match, so
+        you can't match against properties with those names. Custom brains may
+        also add new reserved words. For example, the HttpBrain adds http as a
+        reserved word.
 
     :param target_dict: dict of object properties
-    Target dicts contain as much information as we can about the object being
-    operated on.
+
+      Target dicts contain as much information as we can about the object being
+      operated on.
 
     :param credentials_dict: dict of actor properties
-    Credentials dicts contain as much information as we can about the user
-    performing the action.
 
-    :raises NotAuthorized if the check fails
+      Credentials dicts contain as much information as we can about the user
+      performing the action.
+
+    :raises NotAuthorized: if the check fails
 
     """
     global _BRAIN
diff --git a/nova/compat/flagfile.py b/nova/compat/flagfile.py
index 02d571cb..e62bee13 100644
--- a/nova/compat/flagfile.py
+++ b/nova/compat/flagfile.py
@@ -169,7 +169,7 @@ def handle_flagfiles(args, tempdir=None):
 def handle_flagfiles_managed(args):
     '''A context manager for handle_flagfiles() which removes temp files.
 
-    For use with the 'with' statement, i.e.
+    For use with the 'with' statement, i.e.::
 
         with handle_flagfiles_managed(args) as args:
              # Do stuff
diff --git a/nova/notifier/api.py b/nova/notifier/api.py
index f4532e82..5af16cba 100644
--- a/nova/notifier/api.py
+++ b/nova/notifier/api.py
@@ -79,35 +79,35 @@ def publisher_id(service, host=None):
 
 
 def notify(publisher_id, event_type, priority, payload):
-    """
-    Sends a notification using the specified driver
+    """Sends a notification using the specified driver
 
-    Notify parameters:
-
-    publisher_id - the source worker_type.host of the message
-    event_type - the literal type of event (ex. Instance Creation)
-    priority - patterned after the enumeration of Python logging levels in
-               the set (DEBUG, WARN, INFO, ERROR, CRITICAL)
-    payload - A python dictionary of attributes
+    :param publisher_id: the source worker_type.host of the message
+    :param event_type:   the literal type of event (ex. Instance Creation)
+    :param priority:     patterned after the enumeration of Python logging
+                         levels in the set (DEBUG, WARN, INFO, ERROR, CRITICAL)
+    :param payload:       A python dictionary of attributes
 
     Outgoing message format includes the above parameters, and appends the
     following:
 
-    message_id - a UUID representing the id for this notification
-    timestamp - the GMT timestamp the notification was sent at
+    message_id
+      a UUID representing the id for this notification
+
+    timestamp
+      the GMT timestamp the notification was sent at
 
     The composite message will be constructed as a dictionary of the above
     attributes, which will then be sent via the transport mechanism defined
     by the driver.
 
-    Message example:
+    Message example::
 
-    {'message_id': str(uuid.uuid4()),
-     'publisher_id': 'compute.host1',
-     'timestamp': utils.utcnow(),
-     'priority': 'WARN',
-     'event_type': 'compute.create_instance',
-     'payload': {'instance_id': 12, ... }}
+        {'message_id': str(uuid.uuid4()),
+         'publisher_id': 'compute.host1',
+         'timestamp': utils.utcnow(),
+         'priority': 'WARN',
+         'event_type': 'compute.create_instance',
+         'payload': {'instance_id': 12, ... }}
 
     """
     if priority not in log_levels:
diff --git a/nova/scheduler/least_cost.py b/nova/scheduler/least_cost.py
index 899cfd38..8949b983 100644
--- a/nova/scheduler/least_cost.py
+++ b/nova/scheduler/least_cost.py
@@ -79,17 +79,20 @@ def compute_fill_first_cost_fn(host_state, weighing_properties):
 
 def weighted_sum(weighted_fns, host_states, weighing_properties):
     """Use the weighted-sum method to compute a score for an array of objects.
+
     Normalize the results of the objective-functions so that the weights are
     meaningful regardless of objective-function's range.
 
-    host_list - [(host, HostInfo()), ...]
-    weighted_fns - list of weights and functions like:
-        [(weight, objective-functions), ...]
-    weighing_properties is an arbitrary dict of values that can influence
-        weights.
+    :param host_list:    ``[(host, HostInfo()), ...]``
+    :param weighted_fns: list of weights and functions like::
 
-    Returns a single WeightedHost object which represents the best
-    candidate.
+        [(weight, objective-functions), ...]
+
+    :param weighing_properties: an arbitrary dict of values that can
+        influence weights.
+
+    :returns: a single WeightedHost object which represents the best
+              candidate.
     """
 
     # Make a grid of functions results.
diff --git a/nova/vsa/api.py b/nova/vsa/api.py
index 6482a11c..1a03dfb1 100644
--- a/nova/vsa/api.py
+++ b/nova/vsa/api.py
@@ -19,8 +19,9 @@
 Handles all requests relating to Virtual Storage Arrays (VSAs).
 
 Experimental code. Requires special VSA image.
+
 For assistance and guidelines pls contact
-    Zadara Storage Inc & Openstack community
+Zadara Storage Inc & Openstack community
 """
 
 from nova import compute
@@ -143,9 +144,8 @@ class API(base.Base):
     def create(self, context, display_name='', display_description='',
                 vc_count=1, instance_type=None, image_name=None,
                 availability_zone=None, storage=[], shared=None):
-        """
-        Provision VSA instance with corresponding compute instances
-        and associated volumes
+        """Provision VSA instance with compute instances and volumes
+
         :param storage: List of dictionaries with following keys:
                         disk_name, num_disks, size
         :param shared: Specifies if storage is dedicated or shared.