0
# Documentation Generation and Mapping
1

2
Core mapping functionality that converts parsed source code into comprehensive documentation structure. The Mapper handles file discovery, content organization, and output generation using Jinja2 templates and reStructuredText format.
3

4
## Core Mapper Class
5

6
### Mapper
7

8
```python { .api }
9
class Mapper:
10
    """
11
    Maps source code to documentation objects and handles output generation.
12
    
13
    The Mapper coordinates the entire documentation generation pipeline:
14
    - Discovers and loads source files
15
    - Parses code into object representations  
16
    - Maps objects to documentation structure
17
    - Renders output using templates
18
    
19
    Attributes:
20
        objects (list[PythonObject]): Top-level documentation objects
21
        paths (list[str]): Paths to generated documentation files
22
    """
23
    
24
    def load(self, patterns: list[str], dirs: list[str], ignore: list[str]) -> bool:
25
        """
26
        Load and parse source files from specified directories.
27
        
28
        Args:
29
            patterns (list[str]): File patterns to include (e.g., ['*.py', '*.pyi'])
30
            dirs (list[str]): Source directories to scan
31
            ignore (list[str]): Patterns to ignore (e.g., ['*tests*'])
32
            
33
        Returns:
34
            bool: True if any source files were found and loaded
35
            
36
        Recursively discovers Python files, parses them using astroid,
37
        and builds the complete object hierarchy.
38
        """
39
    
40
    def map(self, options: list[str]) -> None:
41
        """
42
        Map loaded objects to documentation structure.
43
        
44
        Args:
45
            options (list[str]): AutoAPI options controlling content inclusion
46
            
47
        Processes the loaded objects according to configuration options:
48
        - Filters objects based on inclusion options
49
        - Resolves inheritance relationships
50
        - Builds cross-reference mappings
51
        - Organizes objects into documentation hierarchy
52
        """
53
    
54
    def output_rst(self, source_suffix: str = '.rst') -> None:
55
        """
56
        Generate reStructuredText documentation files.
57
        
58
        Args:
59
            source_suffix (str): File extension for generated files
60
            
61
        Renders all mapped objects to .rst files using Jinja2 templates:
62
        - Creates individual files for modules, classes, etc.
63
        - Generates index files with navigation
64
        - Applies custom templates if configured
65
        - Writes files to autoapi_root directory
66
        """
67
```
68

69
From `autoapi._mapper`:
70
```python
71
from autoapi._mapper import Mapper
72
```
73

74
## File Discovery and Loading
75

76
### Source File Discovery
77

78
```python { .api }
79
# File pattern matching
80
"""The Mapper discovers source files using glob patterns:
81
- Default patterns: ['*.py', '*.pyi']
82
- Custom patterns via autoapi_file_patterns
83
- Recursive directory scanning
84
- Ignore pattern filtering
85
"""
86

87
# Directory structure handling
88
"""Supports complex project structures:
89
- Single-file modules
90
- Package hierarchies with __init__.py
91
- Namespace packages (PEP 420)
92
- Mixed source and binary distributions
93
"""
94
```
95

96
### Loading Process
97

98
```python { .api }
99
def load(self, patterns, dirs, ignore):
100
    """
101
    Multi-stage loading process:
102
    
103
    1. File Discovery:
104
       - Scan directories recursively
105
       - Apply include/exclude patterns
106
       - Build file path lists
107
    
108
    2. Parsing:
109
       - Parse each file with astroid
110
       - Handle syntax errors gracefully
111
       - Extract object hierarchies
112
    
113
    3. Organization:
114
       - Build package/module structure
115
       - Resolve import relationships
116
       - Create cross-reference mappings
117
    
118
    Returns True if any files were successfully loaded.
119
    """
120
```
121

122
## Object Mapping and Organization
123

124
### Content Filtering
125

126
```python { .api }
127
def map(self, options):
128
    """
129
    Apply AutoAPI options to control content inclusion:
130
    
131
    Options processed:
132
    - 'members': Include documented members
133
    - 'undoc-members': Include undocumented members  
134
    - 'private-members': Include private members (_name)
135
    - 'special-members': Include special methods (__name__)
136
    - 'show-inheritance': Display inheritance relationships
137
    - 'show-module-summary': Generate module summary tables
138
    - 'imported-members': Include imported objects
139
    """
140
```
141

142
### Inheritance Resolution
143

144
```python { .api }
145
# Inheritance processing
146
"""The mapping stage resolves complex inheritance:
147
- Method Resolution Order (MRO) calculation
148
- Inherited member identification
149
- Abstract method detection
150
- Multiple inheritance support
151
- Mixin class handling
152
"""
153

154
# Cross-reference building
155
"""Creates comprehensive cross-reference data:
156
- Type annotation resolution
157
- Import alias tracking
158
- Inter-module references
159
- External package references
160
"""
161
```
162

163
## Template-Based Rendering
164

165
### Template System
166

167
```python { .api }
168
def output_rst(self, source_suffix='.rst'):
169
    """
170
    Template-based rendering system:
171
    
172
    1. Template Selection:
173
       - Object type determines template (class.rst, function.rst)
174
       - Custom templates override defaults
175
       - Template inheritance supported
176
    
177
    2. Context Preparation:
178
       - Object properties and metadata
179
       - Configuration values
180
       - Cross-reference data
181
       - Sphinx-specific context
182
    
183
    3. Rendering:
184
       - Jinja2 template processing
185
       - reStructuredText generation
186
       - File output with proper encoding
187
    """
188
```
189

190
### Template Hierarchy
191

192
```python { .api }
193
# Default templates (autoapi/templates/python/):
194
"""
195
├── base.rst              # Base template with common elements
196
├── index.rst             # Main API index page
197
├── package.rst           # Package documentation
198
├── module.rst            # Module documentation
199
├── class.rst             # Class documentation
200
├── function.rst          # Function documentation
201
├── method.rst            # Method documentation
202
├── property.rst          # Property documentation
203
├── attribute.rst         # Attribute documentation
204
├── data.rst              # Data/variable documentation
205
└── exception.rst         # Exception class documentation
206
"""
207

208
# Template customization
209
"""Custom templates can be provided via:
210
- autoapi_template_dir configuration
211
- Template inheritance from defaults
212
- Per-object-type template overrides
213
"""
214
```
215

216
## Configuration Integration
217

218
### Sphinx Configuration
219

220
```python { .api }
221
# Mapper uses Sphinx configuration values:
222
"""
223
- autoapi_root: Output directory for generated files
224
- autoapi_own_page_level: Level for separate pages
225
- autoapi_member_order: Member ordering preference
226
- autoapi_include_summaries: Summary table generation
227
- autoapi_template_dir: Custom template directory
228
- autoapi_prepare_jinja_env: Environment customization
229
"""
230
```
231

232
### Output Organization
233

234
```python { .api }
235
# Generated file structure:
236
"""
237
autoapi/                  # Default autoapi_root
238
├── index.rst            # Main API index
239
├── package_name/        # Package directory
240
│   ├── index.rst       # Package index
241
│   ├── module.rst      # Module documentation
242
│   └── subpackage/     # Nested packages
243
└── _templates/         # Template overrides (if any)
244
"""
245

246
# Page level control:
247
"""
248
autoapi_own_page_level determines file organization:
249
- 'module': Each module gets own file
250
- 'class': Each class gets own file  
251
- 'function': Each function gets own file
252
"""
253
```
254

255
## Error Handling and Robustness
256

257
### Graceful Degradation
258

259
```python { .api }
260
# Error handling strategies:
261
"""
262
1. Parse Errors:
263
   - Log syntax errors with file/line info
264
   - Continue processing other files
265
   - Generate partial documentation
266

267
2. Import Resolution:
268
   - Handle missing dependencies gracefully
269
   - Use string representations for unresolved types
270
   - Maintain cross-references where possible
271

272
3. Template Errors:
273
   - Fall back to simpler templates
274
   - Log rendering issues
275
   - Generate basic documentation over none
276

277
4. File System:
278
   - Handle permission issues
279
   - Create directories as needed
280
   - Atomic file writing where possible
281
"""
282
```
283

284
## Advanced Features
285

286
### Custom Jinja Environment
287

288
```python { .api }
289
def prepare_jinja_env(jinja_env):
290
    """
291
    Customize Jinja2 environment for advanced template features.
292
    
293
    Args:
294
        jinja_env: Jinja2 environment instance
295
        
296
    Can be configured via autoapi_prepare_jinja_env:
297
    - Add custom filters
298
    - Register template functions
299
    - Configure autoescape settings
300
    - Add template globals
301
    """
302
```
303

304
### Integration Hooks
305

306
```python { .api }
307
# Sphinx event integration:
308
"""
309
The Mapper integrates with Sphinx events:
310
- autoapi-skip-member: Filter objects during mapping
311
- build-finished: Clean up generated files
312
- source-read: Populate cross-references
313
"""
314
```
315

316
## Usage Example
317

318
```python { .api }
319
from autoapi._mapper import Mapper
320

321
# Create and configure mapper
322
mapper = Mapper()
323

324
# Load source files
325
success = mapper.load(
326
    patterns=['*.py', '*.pyi'],
327
    dirs=['src', 'mypackage'],
328
    ignore=['*tests*', '*migrations*']
329
)
330

331
if success:
332
    # Map objects with options
333
    mapper.map([
334
        'members',
335
        'undoc-members',
336
        'show-inheritance',
337
        'show-module-summary'
338
    ])
339
    
340
    # Generate documentation files
341
    mapper.output_rst('.rst')
342
    
343
    # Access generated objects
344
    for obj in mapper.objects:
345
        print(f"Generated docs for: {obj.name}")
346
```
347

348
The Mapper provides the core engine for converting Python source code into comprehensive, navigable documentation that integrates seamlessly with Sphinx documentation systems.