0
# Enhanced Autosummary
1

2
Improved automatic summary table generation with bug fixes, `__all__` support, and customizable column widths. These enhancements address limitations in Sphinx's built-in autosummary functionality while adding new features for better table organization.
3

4
## Capabilities
5

6
### Enhanced Autosummary Directive
7

8
Improved autosummary directive with bug fixes and additional features.
9

10
```python { .api }
11
class PatchedAutosummary(Autosummary):
12
    """Enhanced autosummary directive with bug fixes and improvements."""
13
    
14
    option_spec = {
15
        'toctree': directives.unchanged,
16
        'nosignatures': directives.flag,
17
        'template': directives.unchanged,
18
        'recursive': directives.flag,
19
        'caption': directives.unchanged,
20
        # Enhanced options
21
        'col-widths': directives.unchanged,
22
        'member-order': directives.unchanged,
23
    }
24
    
25
    def run(self) -> List[Node]:
26
        """Run autosummary with enhancements."""
27
        
28
    def get_items(self, names: List[str]) -> List[Tuple[str, str, str, str]]:
29
        """Get autosummary items with improved member detection."""
30
        
31
    def import_by_name(self, name: str, prefixes: List[str]) -> Tuple[str, Any, Any, str]:
32
        """Import object by name with better error handling."""
33
```
34

35
### Enhanced Module Documenter
36

37
Module documenter with proper `__all__` attribute support and improved member filtering.
38

39
```python { .api }
40
class PatchedAutoSummModuleDocumenter(ModuleDocumenter):
41
    """Module documenter with __all__ support and enhanced filtering."""
42
    
43
    def get_object_members(self, want_all: bool) -> Tuple[bool, List[Tuple[str, Any]]]:
44
        """
45
        Get module members with proper __all__ handling.
46
        
47
        Args:
48
            want_all: Whether to include all members or just public ones
49
            
50
        Returns:
51
            Tuple of (members_check_module, members_list)
52
        """
53
        
54
    def filter_members(self, members: List[Tuple[str, Any]], want_all: bool) -> List[Tuple[str, Any, bool]]:
55
        """Filter members based on __all__ and other criteria."""
56
        
57
    def sort_members(self, documenters: List[Tuple[Documenter, bool]], order: str) -> List[Tuple[Documenter, bool]]:
58
        """Sort members according to specified order."""
59
```
60

61
### Enhanced Class Documenter
62

63
Class documenter with improved inheritance handling and member organization.
64

65
```python { .api }
66
class PatchedAutoSummClassDocumenter(ClassDocumenter):
67
    """Class documenter with enhanced member handling."""
68
    
69
    def get_object_members(self, want_all: bool) -> Tuple[bool, List[Tuple[str, Any]]]:
70
        """Get class members with improved inheritance handling."""
71
        
72
    def filter_members(self, members: List[Tuple[str, Any]], want_all: bool) -> List[Tuple[str, Any, bool]]:
73
        """Filter class members with better attribute detection."""
74
        
75
    def document_members(self, all_members: bool = False) -> None:
76
        """Document class members with enhanced organization."""
77
```
78

79
### Documenter Selection
80

81
Improved documenter selection logic for different object types.
82

83
```python { .api }
84
def get_documenter(app: Sphinx, obj: Any, parent: Any) -> Type[Documenter]:
85
    """
86
    Return appropriate documenter class for object.
87
    
88
    Args:
89
        app: Sphinx application instance
90
        obj: Object to document
91
        parent: Parent object
92
        
93
    Returns:
94
        Documenter class that can handle the object
95
    """
96

97
def get_documenter_by_type(objtype: str, app: Sphinx) -> Type[Documenter]:
98
    """Get documenter class by object type string."""
99
```
100

101
### Column Width Configuration
102

103
Customizable column widths for autosummary tables in LaTeX and HTML output.
104

105
```python { .api }
106
class AutosummaryWidths:
107
    """Configures autosummary table column widths."""
108
    
109
    def __init__(self, signature_width: str = "0.6\\linewidth", 
110
                 summary_width: str = "0.4\\linewidth") -> None:
111
        """
112
        Initialize column width configuration.
113
        
114
        Args:
115
            signature_width: Width for signature column
116
            summary_width: Width for summary column
117
        """
118
        
119
    def apply_to_table(self, table_node: table) -> None:
120
        """Apply width configuration to table node."""
121

122
class WidthsDirective(SphinxDirective):
123
    """Directive for setting autosummary column widths."""
124
    
125
    option_spec = {
126
        'signature': directives.unchanged,
127
        'summary': directives.unchanged,
128
    }
129
    
130
    def run(self) -> List[Node]:
131
        """Set column widths for subsequent autosummary tables."""
132
```
133

134
Usage:
135

136
```rst
137
.. autosummary-widths::
138
   :signature: 0.7\linewidth
139
   :summary: 0.3\linewidth
140

141
.. autosummary::
142
   :toctree: generated/
143
   
144
   module.function1
145
   module.function2
146
   module.Class1
147
```
148

149
### Member Ordering
150

151
Enhanced member ordering options for autosummary tables.
152

153
```python { .api }
154
def sort_members_by_type(members: List[Tuple[str, Any]]) -> List[Tuple[str, Any]]:
155
    """Sort members by type (classes, functions, data)."""
156

157
def sort_members_alphabetical(members: List[Tuple[str, Any]]) -> List[Tuple[str, Any]]:
158
    """Sort members alphabetically."""
159

160
def sort_members_by_source(members: List[Tuple[str, Any]]) -> List[Tuple[str, Any]]:
161
    """Sort members by source code order."""
162

163
def sort_members_grouped(members: List[Tuple[str, Any]]) -> List[Tuple[str, Any]]:
164
    """Sort members in logical groups (classes, functions, exceptions, data)."""
165
```
166

167
Configuration:
168

169
```python
170
# Member ordering options
171
autodocsumm_member_order = "bysource"  # "alphabetical", "groupwise", "bysource"
172
```
173

174
### Template Enhancements
175

176
Enhanced templates for autosummary generation with better formatting.
177

178
```python { .api }
179
def render_autosummary_template(template_name: str, context: Dict[str, Any]) -> str:
180
    """
181
    Render autosummary template with enhanced context.
182
    
183
    Args:
184
        template_name: Name of template to render
185
        context: Template context variables
186
        
187
    Returns:
188
        Rendered template content
189
    """
190

191
class EnhancedTemplateLoader:
192
    """Template loader with enhanced autosummary templates."""
193
    
194
    def get_template(self, name: str) -> Template:
195
        """Get template with fallback to enhanced versions."""
196
```
197

198
### Signature Formatting
199

200
Improved signature formatting for autosummary tables.
201

202
```python { .api }
203
def format_signature(obj: Any, max_width: int = 60) -> str:
204
    """
205
    Format object signature for autosummary display.
206
    
207
    Args:
208
        obj: Object to format signature for
209
        max_width: Maximum width for signature
210
        
211
    Returns:
212
        Formatted signature string
213
    """
214

215
def format_summary(docstring: str, max_length: int = 120) -> str:
216
    """
217
    Extract and format summary from docstring.
218
    
219
    Args:
220
        docstring: Full docstring text
221
        max_length: Maximum summary length
222
        
223
    Returns:
224
        Formatted summary text
225
    """
226
```
227

228
### Cross-Reference Improvements
229

230
Enhanced cross-referencing for autosummary items.
231

232
```python { .api }
233
def resolve_autosummary_references(app: Sphinx, env: BuildEnvironment, 
234
                                 node: Node, contnode: Node) -> Optional[Node]:
235
    """
236
    Resolve cross-references in autosummary tables.
237
    
238
    Args:
239
        app: Sphinx application
240
        env: Build environment
241
        node: Reference node
242
        contnode: Content node
243
        
244
    Returns:
245
        Resolved reference node or None
246
    """
247
```
248

249
### Configuration Options
250

251
Enhanced autosummary adds several configuration options:
252

253
```python
254
# Column width configuration
255
autosummary_col_type = "p{0.5\\linewidth}"  # LaTeX column type
256
autosummary_signature_width = "0.6\\linewidth"
257
autosummary_summary_width = "0.4\\linewidth"
258

259
# Member organization
260
autodocsumm_member_order = "bysource"  # "alphabetical", "groupwise", "bysource"  
261
autosummary_generate = True
262
autosummary_generate_overwrite = True
263

264
# Template configuration
265
autosummary_mock_imports = []
266
autosummary_imported_members = False
267
```
268

269
### Usage Examples
270

271
Basic autosummary with enhancements:
272

273
```rst
274
.. autosummary::
275
   :toctree: generated/
276
   :nosignatures:
277
   :member-order: groupwise
278
   
279
   mymodule.Class1
280
   mymodule.Class2
281
   mymodule.function1
282
   mymodule.function2
283
   mymodule.CONSTANT1
284
```
285

286
With custom column widths:
287

288
```rst
289
.. autosummary-widths::
290
   :signature: 0.7\linewidth
291
   :summary: 0.3\linewidth
292

293
.. autosummary::
294
   :toctree: generated/
295
   :template: custom_class.rst
296
   
297
   mymodule
298
```
299

300
Recursive autosummary:
301

302
```rst
303
.. autosummary::
304
   :toctree: generated/
305
   :recursive:
306
   :template: custom_module.rst
307
   
308
   mypackage
309
```
310

311
### Import Resolution
312

313
Enhanced import resolution and member discovery for autosummary.
314

315
```python { .api }
316
def import_by_name(name: str, prefixes: List[str] = []) -> Tuple[str, Any, Any, str]:
317
    """
318
    Import object by name with enhanced error handling.
319
    
320
    Args:
321
        name: Object name to import
322
        prefixes: List of prefixes to try
323
        
324
    Returns:
325
        Tuple of (name, obj, parent, modname)
326
    """
327

328
def resolve_name(name: str, modname: str) -> Tuple[str, str, str, str]:
329
    """
330
    Resolve object name within module context.
331
    
332
    Args:
333
        name: Object name
334
        modname: Module name
335
        
336
    Returns:
337
        Tuple of resolved names
338
    """
339

340
class ImportResolver:
341
    """Enhanced import resolution for autosummary."""
342
    
343
    def __init__(self, app: Sphinx) -> None: ...
344
    
345
    def resolve_import(self, name: str) -> Optional[Any]:
346
        """Resolve import with fallback strategies."""
347
        
348
    def get_module_members(self, modname: str) -> List[str]:
349
        """Get all members of a module."""
350
```
351

352
### Custom Autosummary Generation
353

354
Advanced autosummary generation with custom templates and processing.
355

356
```python { .api }
357
def generate_autosummary_content(names: List[str], imported_members: bool = False, 
358
                               app: Optional[Sphinx] = None) -> str:
359
    """
360
    Generate autosummary content programmatically.
361
    
362
    Args:
363
        names: List of names to generate summaries for
364
        imported_members: Include imported members
365
        app: Sphinx application instance
366
        
367
    Returns:
368
        Generated autosummary content
369
    """
370

371
class AutosummaryGenerator:
372
    """Advanced autosummary content generator."""
373
    
374
    def __init__(self, app: Sphinx, template_dir: Optional[str] = None) -> None: ...
375
    
376
    def generate_summary_table(self, items: List[Tuple[str, str, str, str]]) -> str:
377
        """Generate HTML summary table."""
378
        
379
    def generate_toctree(self, items: List[str]) -> str:
380
        """Generate toctree for autosummary items."""
381
```
382

383
### Error Handling
384

385
The enhanced autosummary includes robust error handling:
386

387
```python { .api }
388
class AutosummaryError(SphinxError):
389
    """Base exception for autosummary errors."""
390

391
class MemberImportError(AutosummaryError):
392
    """Raised when member import fails."""
393

394
class TemplateError(AutosummaryError):
395
    """Raised when template processing fails."""
396

397
class AutosummaryConfigError(AutosummaryError):
398
    """Raised when autosummary configuration is invalid."""
399
```