0
# Help System
1

2
Comprehensive help system providing contextual documentation for AWS CLI commands, services, and operations. The help system renders documentation in multiple formats and integrates with platform-specific viewers for optimal user experience.
3

4
## Capabilities
5

6
### Help Command Classes
7

8
Base help command infrastructure for rendering documentation at different command hierarchy levels.
9

10
```python { .api }
11
class HelpCommand:
12
    def __init__(self, session, command_table, arg_table, name, event_class=None):
13
        """
14
        Base help command class.
15
        
16
        Parameters:
17
            session: botocore.session.Session, AWS session
18
            command_table: dict, available commands
19
            arg_table: dict, command arguments
20
            name: str, command name
21
            event_class: str, event class for customization
22
        """
23
    
24
    def create_help_command(self):
25
        """Create help command instance."""
26
    
27
    def __call__(self, args, parsed_globals):
28
        """Execute help command."""
29

30
class ProviderHelpCommand(HelpCommand):
31
    """
32
    Top-level AWS CLI help command (aws help).
33
    Provides overview of AWS CLI and available services.
34
    """
35

36
class ServiceHelpCommand(HelpCommand):
37
    """
38
    Service-level help command (aws s3 help).
39
    Provides service overview and available operations.
40
    """
41

42
class OperationHelpCommand(HelpCommand):
43
    """
44
    Operation-level help command (aws s3 ls help).
45
    Provides detailed operation documentation and parameter descriptions.
46
    """
47
```
48

49
### Help Rendering System
50

51
Platform-aware help rendering with support for multiple output formats and viewers.
52

53
```python { .api }
54
def get_renderer():
55
    """
56
    Get platform-appropriate help renderer.
57
    
58
    Returns:
59
        Help renderer instance for current platform
60
    """
61

62
class PosixHelpRenderer:
63
    """
64
    Unix/Linux help renderer using less or similar pagers.
65
    Supports color output and interactive navigation.
66
    """
67
    
68
    def render(self, contents):
69
        """
70
        Render help content using system pager.
71
        
72
        Parameters:
73
            contents: str, help content to render
74
        """
75

76
class WindowsHelpRenderer:
77
    """
78
    Windows help renderer with fallback to console output.
79
    Handles Windows-specific paging and display considerations.
80
    """
81
    
82
    def render(self, contents):
83
        """
84
        Render help content on Windows platform.
85
        
86
        Parameters:
87
            contents: str, help content to render
88
        """
89
```
90

91
### Help Content Generation
92

93
Documentation generation from AWS service models and command definitions.
94

95
```python { .api }
96
class HelpRenderer:
97
    """Base class for help content rendering."""
98
    
99
    def render_to_text(self, help_command):
100
        """
101
        Render help command to text format.
102
        
103
        Parameters:
104
            help_command: HelpCommand instance
105
            
106
        Returns:
107
            str: Formatted help text
108
        """
109

110
class OperationDocumentEventHandler:
111
    """
112
    Event handler for operation documentation generation.
113
    Processes service models to generate help content.
114
    """
115
    
116
    def doc_description(self, help_command, **kwargs):
117
        """Generate operation description."""
118
    
119
    def doc_synopsis(self, help_command, **kwargs):
120
        """Generate operation synopsis."""
121
    
122
    def doc_options(self, help_command, **kwargs):  
123
        """Generate operation options documentation."""
124
```
125

126
**Usage Example:**
127
```python
128
from awscli.help import ProviderHelpCommand, ServiceHelpCommand
129
import botocore.session
130

131
# Create help for top-level AWS CLI
132
session = botocore.session.Session()
133
help_cmd = ProviderHelpCommand(
134
    session=session,
135
    command_table={},  # Would be populated with actual commands
136
    arg_table={},
137
    name='aws'
138
)
139

140
# Execute help command
141
help_cmd([], {})  # Shows top-level AWS CLI help
142

143
# Create service-level help
144
service_help = ServiceHelpCommand(
145
    session=session,
146
    command_table={},
147
    arg_table={},
148
    name='s3'
149
)
150
service_help([], {})  # Shows S3 service help
151
```
152

153
## Help System Exceptions
154

155
Specialized exceptions for help rendering and display issues.
156

157
```python { .api }
158
class ExecutableNotFoundError(Exception):
159
    """
160
    Raised when required executable for help rendering is not found.
161
    Typically occurs when system pager is not available.
162
    """
163
```
164

165
## Advanced Help Integration
166

167
### Custom Help Documentation
168

169
Custom commands can provide their own help documentation:
170

171
```python
172
from awscli.customizations.commands import BasicCommand
173

174
class MyCommand(BasicCommand):
175
    NAME = 'my-command'
176
    DESCRIPTION = 'Custom command description'
177
    SYNOPSIS = 'aws my-command [options]'
178
    EXAMPLES = '''
179
Examples:
180
  aws my-command --input file.txt
181
    Process input file
182
    
183
  aws my-command --format json --output results.json
184
    Process with JSON output format
185
    '''
186
    
187
    def create_help_command(self):
188
        """Create custom help command with enhanced documentation."""
189
        help_command = super().create_help_command()
190
        # Add custom help sections
191
        return help_command
192
```
193

194
### Help System Event Integration
195

196
The help system integrates with the AWS CLI event system for customization:
197

198
```python
199
# Register custom help handler
200
session.register('doc-description.s3.cp', custom_help_handler)
201

202
def custom_help_handler(help_command, **kwargs):
203
    """Custom help content handler."""
204
    help_command.doc.style.h2('Custom Section')
205
    help_command.doc.write('Additional documentation content.')
206
```
207

208
### Interactive Help Features
209

210
- **Pager Integration**: Automatically uses system pager (less, more) for long content
211
- **Color Support**: Syntax highlighting and colored output where supported  
212
- **Search Integration**: Integration with pager search functionality
213
- **Cross-references**: Links between related commands and concepts
214
- **Examples**: Comprehensive usage examples with explanations
215

216
### Platform-Specific Behavior
217

218
**Unix/Linux:**
219
- Uses `less` pager with color support
220
- Supports interactive navigation and search
221
- Handles terminal width detection
222

223
**Windows:**
224
- Falls back to console output if pager unavailable
225
- Handles Windows console encoding issues
226
- Provides pagination for long content
227

228
**Integration Example:**
229
```python
230
from awscli.help import get_renderer
231

232
# Get platform-appropriate renderer
233
renderer = get_renderer()
234

235
# Render help content with platform-specific handling
236
help_content = """
237
AWS CLI Help
238
============
239

240
The AWS Command Line Interface...
241
"""
242

243
renderer.render(help_content)
244
```