refactor: address doc quality issues

Author: mariajgrimaldi

openedx_authz/api/data.py

@@ -7,6 +7,19 @@
 from opaque_keys import InvalidKeyError
 from opaque_keys.edx.locator import LibraryLocatorV2
 
+
+__all__ = [
+    "UserData",
+    "PermissionData",
+    "GroupingPolicyIndex",
+    "PolicyIndex",
+    "ActionData",
+    "RoleAssignmentData",
+    "RoleData",
+    "ScopeData",
+    "SubjectData",
+]
+
 AUTHZ_POLICY_ATTRIBUTES_SEPARATOR = "^"
 
 
@@ -289,6 +302,10 @@ class UserData(SubjectData):
     def username(self) -> str:
         """The username for the user (e.g., 'john_doe').
 
+        TODO: Temporary :no-index: to avoid duplicate object warnings from wildcard import in __init__.py
+
+        :no-index:
+
         This is an alias for external_key that represents the username without the namespace prefix.
 
         Returns:
@@ -358,16 +375,22 @@ class RoleData(AuthZData):
         permissions: A list of permissions assigned to the role.
         metadata: A dictionary of metadata assigned to the role. This can include
             information such as the description of the role, creation date, etc.
+
+    TODO: Temporary :no-index: on attributes to avoid duplicate object warnings from wildcard import in __init__.py
     """
 
     NAMESPACE: ClassVar[str] = "role"
-    permissions: list[PermissionData] = None
-    metadata: RoleMetadataData = None
+    permissions: list[PermissionData] = None  #: :no-index:
+    metadata: RoleMetadataData = None  #: :no-index:
 
     @property
     def name(self) -> str:
         """The human-readable name of the role (e.g., 'Library Admin', 'Course Instructor').
 
+        TODO: Temporary :no-index: to avoid duplicate object warnings from wildcard import in __init__.py
+
+        :no-index:
+
         This property transforms the external_key into a human-readable display name
         by replacing underscores with spaces and capitalizing each word.
 
@@ -386,8 +409,10 @@ class RoleAssignmentData(AuthZData):
         email: The email of the user.
         role_name: The name of the role.
         scope: The scope in which the role is assigned.
+
+    TODO: Temporary :no-index: on attributes to avoid duplicate object warnings from wildcard import in __init__.py
     """
 
-    subject: SubjectData = None  # Needs defaults to avoid value error from attrs
+    subject: SubjectData = None  #: :no-index:
     role: RoleData = None
-    scope: ScopeData = None
+    scope: ScopeData = None  #: :no-index:

openedx_authz/api/roles.py

@@ -87,7 +87,8 @@ def get_permissions_for_active_roles_in_scope(
     This function operates on the principle that roles defined in policies are templates
     that become active only when assigned to subjects with specific scopes.
 
-    Role Definition vs Role Assignment:
+    **Role Definition vs Role Assignment:**
+
     - Policy roles define potential permissions with namespace patterns (e.g., 'lib@*')
     - Actual permissions are granted only when roles are assigned to subjects with
       concrete scopes (e.g., 'lib@123')
@@ -96,7 +97,8 @@ def get_permissions_for_active_roles_in_scope(
     - The specific scope at assignment time ('lib@123') determines the exact
       resource the permissions apply to
 
-    Behavior:
+    **Behavior:**
+
     - Returns permissions only for roles that have been assigned to subjects
     - Unassigned roles (those defined in policy but not given to any subject)
       contribute no permissions to the result