0
# Autodoc Enhancements
1

2
Enhancements to Sphinx's autodoc functionality that improve attribute documentation, particularly for complex class hierarchies and metaclass properties. These enhancements are essential for properly documenting advanced Python class patterns.
3

4
## Capabilities
5

6
### Enhanced Attribute Access
7

8
Improved attribute getter for type objects (classes) that handles metaclass properties correctly, ensuring that class-level properties are documented properly rather than being overshadowed by metaclass implementations.
9

10
```python { .api }
11
def type_object_attrgetter(obj: type, attr: str, *defargs) -> object:
12
    """
13
    Enhanced attrgetter for type objects that handles metaclass properties.
14
    
15
    This function provides improved attribute access for classes that can handle
16
    class attributes implemented as properties on a metaclass. Unlike regular
17
    getattr(), this function returns the property object defined on the class
18
    rather than resolving metaclass properties.
19
    
20
    Parameters:
21
    - obj: The class object to get the attribute from
22
    - attr: Name of the attribute to retrieve
23
    - *defargs: Default arguments if attribute is not found
24
    
25
    Returns:
26
    - object: The requested attribute, preferring class-defined properties
27
             over metaclass properties
28
    
29
    Raises:
30
    - AttributeError: If attribute is not found and no default provided
31
    """
32
```
33

34
#### Usage Example
35

36
```python
37
from sphinx_automodapi.autodoc_enhancements import type_object_attrgetter
38

39
class Meta(type):
40
    @property
41
    def foo(cls):
42
        return 'metaclass foo'
43

44
class MyClass(metaclass=Meta):
45
    @property
46
    def foo(self):
47
        """Docstring for MyClass.foo property."""
48
        return 'instance foo'
49

50
# Regular getattr returns metaclass property value
51
regular_result = getattr(MyClass, 'foo')  # 'metaclass foo'
52

53
# Enhanced getter returns the class property object
54
enhanced_result = type_object_attrgetter(MyClass, 'foo')  # <property object>
55
docstring = enhanced_result.__doc__  # 'Docstring for MyClass.foo property.'
56
```
57

58
### Dataclass Support
59

60
Enhanced attribute access includes special handling for dataclass fields, allowing proper documentation of dataclass attributes even when they don't have default values.
61

62
```python { .api }
63
# Dataclass field handling is built into type_object_attrgetter
64
# When AttributeError occurs, checks for dataclass fields:
65
# - Detects if obj is a dataclass using dataclasses.is_dataclass()
66
# - Looks up attribute in obj.__dataclass_fields__
67
# - Returns field.default if available
68
```
69

70
## Integration with Sphinx
71

72
### Setup Function
73

74
```python { .api }
75
def setup(app: Sphinx) -> dict[str, bool]:
76
    """
77
    Set up autodoc enhancements with Sphinx.
78
    
79
    Registers the enhanced attribute getter and configures autodoc
80
    to use improved attribute access for type objects.
81
    
82
    Parameters:
83
    - app: Sphinx application instance
84
    
85
    Returns:
86
    - dict: Parallel processing compatibility flags
87
    
88
    Actions performed:
89
    - Sets up sphinx.ext.autodoc extension as dependency
90
    - Registers type_object_attrgetter for type objects
91
    - Configures AttributeDocumenter
92
    - Manages warning suppression during setup
93
    """
94
```
95

96
### Attribute Documenter Configuration
97

98
The setup process includes configuration of Sphinx's AttributeDocumenter to work properly with the enhanced attribute access:
99

100
```python
101
# Internal setup details:
102
app.add_autodoc_attrgetter(type, type_object_attrgetter)
103
app.add_autodocumenter(AttributeDocumenter)
104
```
105

106
## Implementation Details
107

108
### Method Resolution Order (MRO) Handling
109

110
The enhanced attribute getter uses Python's Method Resolution Order to find the correct attribute definition:
111

112
1. **MRO Traversal**: Searches through `obj.__mro__` to find where the attribute is defined
113
2. **Property Detection**: Checks if the attribute in `base.__dict__[attr]` is a property
114
3. **Direct Return**: Returns the property object directly for documentation purposes
115
4. **Fallback**: Uses regular `getattr()` for non-property attributes
116

117
### Metaclass Property Handling
118

119
The key improvement addresses a common issue in Python class documentation:
120

121
- **Problem**: `getattr(cls, 'property_name')` resolves metaclass properties, hiding class properties
122
- **Solution**: Direct `__dict__` access finds class-defined properties before metaclass resolution
123
- **Benefit**: Autodoc can properly document class properties with their actual docstrings
124

125
### Dataclass Integration
126

127
Special handling for dataclass fields ensures comprehensive attribute documentation:
128

129
```python
130
# Dataclass field resolution logic:
131
if dataclasses.is_dataclass(obj) and attr in obj.__dataclass_fields__:
132
    return obj.__dataclass_fields__[attr].default
133
```
134

135
## Type Definitions
136

137
```python { .api }
138
# Type hints used in the module
139
from typing import Any
140
from sphinx.application import Sphinx
141

142
# Internal constants
143
class_types = (type,)
144
MethodDescriptorType = type(type.__subclasses__)
145
```
146

147
## Use Cases
148

149
### Complex Class Hierarchies
150

151
When documenting frameworks or libraries with sophisticated class hierarchies where properties are defined at multiple levels.
152

153
### Metaclass-Heavy Code
154

155
Essential for documenting code that makes extensive use of metaclasses, such as ORMs, validation frameworks, or DSL implementations.
156

157
### Dataclass Documentation
158

159
Improves documentation quality for dataclass-heavy codebases by ensuring all fields are properly documented even when they lack explicit defaults.
160

161
## Compatibility
162

163
The enhancements are designed to:
164
- Work transparently with existing Sphinx autodoc functionality
165
- Maintain backward compatibility with standard attribute access
166
- Integrate seamlessly with other sphinx-automodapi components
167
- Support parallel documentation generation
168

169
The module serves as a foundation for other sphinx-automodapi components, providing the enhanced attribute access needed for comprehensive API documentation generation.