0
# Smart Reference Resolution
1

2
Handles the mapping between API locations (where users import classes from) and source locations (where classes are actually defined), ensuring that cross-references work correctly in complex package hierarchies. This is essential for projects where the public API differs from the internal code organization.
3

4
## Capabilities
5

6
### Docstring Processing
7

8
Builds mappings between actual class locations and their API locations during the documentation build process.
9

10
```python { .api }
11
def process_docstring(app: Sphinx, what: str, name: str, obj: object, 
12
                     options: dict, lines: list[str]) -> None:
13
    """
14
    Process docstrings to build class name mappings.
15
    
16
    Connected to Sphinx's 'autodoc-process-docstring' event to track class
17
    locations and build a mapping from actual module.Class names to their
18
    API names.
19
    
20
    Parameters:
21
    - app: Sphinx application instance
22
    - what: Type of object being documented ('class', 'function', etc.)
23
    - name: The API name of the object
24
    - obj: The actual Python object being documented
25
    - options: Autodoc options
26
    - lines: Docstring lines (not modified by this function)
27
    
28
    Side Effects:
29
    - Updates app.env.class_name_mapping dictionary with mappings
30
    """
31
```
32

33
#### Usage Example
34

35
The function runs automatically during documentation generation. For a class defined at `mypackage.internal.utils.Helper` but imported as `mypackage.Helper`, it creates the mapping:
36

37
```python
38
# Internal mapping created:
39
env.class_name_mapping['mypackage.internal.utils.Helper'] = 'mypackage.Helper'
40
```
41

42
### Reference Resolution
43

44
Resolves missing references by looking up class names in the mapping and creating proper cross-references.
45

46
```python { .api }
47
def missing_reference_handler(app: Sphinx, env: BuildEnvironment, node: Node, 
48
                             contnode: Element) -> Element:
49
    """
50
    Handle missing references by resolving through name mappings.
51
    
52
    Connected to Sphinx's 'missing-reference' event. When Sphinx cannot
53
    resolve a reference, this handler checks if it can be resolved using
54
    the class name mappings built during docstring processing.
55
    
56
    Parameters:
57
    - app: Sphinx application instance
58
    - env: Build environment containing the class name mappings
59
    - node: The pending_xref node that couldn't be resolved
60
    - contnode: The node containing the text and formatting
61
    
62
    Returns:
63
    - Element: New resolved reference node, or None if still unresolvable
64
    """
65
```
66

67
#### Usage Example
68

69
When documentation contains a reference like `:class:`mypackage.internal.utils.Helper`` but the user-facing API is `mypackage.Helper`, this function:
70

71
1. Detects the missing reference to `mypackage.internal.utils.Helper`
72
2. Looks up the mapping to find `mypackage.Helper`
73
3. Creates a new reference node pointing to the correct documentation
74

75
### Environment Management
76

77
Handles merging of class name mappings when Sphinx processes multiple documentation sources.
78

79
```python { .api }
80
def merge_mapping(app: Sphinx, env: BuildEnvironment, docnames: set[str], 
81
                 env_other: BuildEnvironment) -> None:
82
    """
83
    Merge class name mappings between build environments.
84
    
85
    Connected to Sphinx's environment merge events to ensure class name
86
    mappings are preserved when environments are combined during parallel
87
    builds or incremental updates.
88
    
89
    Parameters:
90
    - app: Sphinx application instance
91
    - env: Primary build environment
92
    - docnames: Set of document names being processed
93
    - env_other: Secondary environment to merge from
94
    
95
    Side Effects:
96
    - Updates env.class_name_mapping with mappings from env_other
97
    """
98
```
99

100
## Extension Setup
101

102
The smart resolver integrates with Sphinx through event connections:
103

104
```python { .api }
105
def setup(app: Sphinx) -> dict[str, bool]:
106
    """
107
    Set up smart reference resolution with Sphinx.
108
    
109
    Connects event handlers:
110
    - 'autodoc-process-docstring': process_docstring
111
    - 'missing-reference': missing_reference_handler
112
    - Environment merge events: merge_mapping
113
    
114
    Returns:
115
    - dict: Parallel processing compatibility flags
116
    """
117
```
118

119
## Common Use Cases
120

121
### Complex Package Hierarchies
122

123
When your package has a complex internal structure but presents a simple public API:
124

125
```python
126
# Internal structure:
127
mypackage/
128
  internal/
129
    core/
130
      algorithms.py  # defines FastSolver class
131
  __init__.py        # imports: from .internal.core.algorithms import FastSolver
132
```
133

134
Users import: `from mypackage import FastSolver`  
135
But autodoc references: `mypackage.internal.core.algorithms.FastSolver`
136

137
The smart resolver maps these correctly so cross-references work.
138

139
### API Reorganization
140

141
When you've reorganized your internal code but maintained backward compatibility in the public API:
142

143
```python
144
# Old location: mypackage.utils.Helper
145
# New location: mypackage.internal.helpers.Helper  
146
# Public API: from mypackage import Helper
147

148
# Smart resolver ensures references to any of these resolve to the same documentation
149
```
150

151
### Inheritance Diagrams
152

153
Inheritance diagrams often reference classes by their canonical (source) location rather than their API location. The smart resolver ensures these references point to the correct documentation pages.
154

155
## Data Structures
156

157
```python { .api }
158
# Environment attribute added by smart resolver
159
class BuildEnvironment:
160
    class_name_mapping: dict[str, str]  # Maps source_name -> api_name
161
```
162

163
The mapping dictionary format:
164
- **Key**: `module.path.ClassName` (where class is actually defined)
165
- **Value**: `api.name.ClassName` (where users import from)
166

167
## Integration Notes
168

169
### Event Timing
170

171
The smart resolver works through Sphinx's event system:
172

173
1. **During docstring processing**: Builds the class name mapping
174
2. **During reference resolution**: Uses the mapping to resolve missing references
175
3. **During environment merging**: Preserves mappings across build processes
176

177
### Compatibility
178

179
The smart resolver is designed to:
180
- Work with parallel documentation builds
181
- Handle incremental builds correctly
182
- Integrate seamlessly with other Sphinx extensions
183
- Preserve existing cross-reference functionality
184

185
### Performance Considerations
186

187
- Mappings are built incrementally during normal documentation processing
188
- No additional parsing or module imports required
189
- Minimal overhead during reference resolution
190
- Memory usage scales with the number of documented classes
191

192
The smart resolver is essential for maintaining clean, working documentation in projects with complex API structures, ensuring that users can navigate documentation seamlessly regardless of internal code organization.