0
# Help and Documentation
1

2
Fire provides comprehensive utilities for generating help text and usage information for CLI components, with support for docstring parsing, automatic formatting, and customizable output.
3

4
## Capabilities
5

6
### Help Text Generation
7

8
Generate formatted help text for any Fire component, including function signatures, docstrings, and usage examples.
9

10
```python { .api }
11
def HelpText(component, trace=None, verbose=False):
12
    """
13
    Generate help text for a component.
14
    
15
    Analyzes the component to extract documentation, signatures, and usage
16
    information, formatting it for display to users.
17
    
18
    Parameters:
19
    - component: Component to generate help for (function, class, module, etc.)
20
    - trace: Optional FireTrace object showing execution path
21
    - verbose: Whether to include private/hidden members and detailed info
22
    
23
    Returns:
24
    String containing formatted help text
25
    """
26
```
27

28
### Usage Text Generation
29

30
Generate concise usage information showing how to invoke a component from the command line.
31

32
```python { .api }
33
def UsageText(component, trace=None, verbose=False):
34
    """
35
    Generate usage text for a component.
36
    
37
    Creates a concise summary of how to use the component from the command line,
38
    including argument names, types, and optional parameters.
39
    
40
    Parameters:
41
    - component: Component to generate usage for
42
    - trace: Optional FireTrace object showing execution path  
43
    - verbose: Whether to include additional usage details
44
    
45
    Returns:
46
    String containing formatted usage text
47
    """
48
```
49

50
## Docstring Processing
51

52
Fire includes comprehensive docstring parsing capabilities for extracting structured information from Python docstrings.
53

54
```python { .api }
55
class DocstringInfo:
56
    """
57
    Information extracted from docstrings (namedtuple).
58
    
59
    Attributes:
60
    - summary: Brief description (first line)
61
    - description: Detailed description  
62
    - args: List of ArgInfo objects for parameters
63
    - returns: Return value description
64
    - yields: Generator yield value description
65
    - raises: Exception information
66
    """
67

68
class ArgInfo:
69
    """
70
    Argument information from docstrings (namedtuple).
71
    
72
    Attributes:
73
    - name: Parameter name
74
    - type: Parameter type annotation or inferred type
75
    - description: Parameter description
76
    """
77

78
class KwargInfo(ArgInfo):
79
    """
80
    Keyword argument information, extends ArgInfo (namedtuple).
81
    
82
    Same attributes as ArgInfo but specifically for keyword arguments.
83
    """
84
```
85

86
## Usage Examples
87

88
**Basic help generation:**
89
```python
90
import fire
91
from fire import helptext
92

93
def process_file(filename, output_dir="./output", verbose=False):
94
    """
95
    Process a file and save results.
96
    
97
    Args:
98
        filename: Path to input file to process
99
        output_dir: Directory to save processed results  
100
        verbose: Enable verbose logging output
101
        
102
    Returns:
103
        Path to the processed output file
104
    """
105
    # Implementation here
106
    pass
107

108
# Generate help text
109
help_text = helptext.HelpText(process_file)
110
print(help_text)
111

112
# Generate usage text  
113
usage_text = helptext.UsageText(process_file)
114
print(usage_text)
115
```
116

117
**Class help generation:**
118
```python
119
import fire
120
from fire import helptext
121

122
class DataAnalyzer:
123
    """Analyze datasets with various statistical methods."""
124
    
125
    def __init__(self, data_path):
126
        """Initialize analyzer with data file path."""
127
        self.data_path = data_path
128
    
129
    def summary(self, include_plots=False):
130
        """
131
        Generate summary statistics.
132
        
133
        Args:
134
            include_plots: Whether to generate visualization plots
135
            
136
        Returns:
137
            Dictionary containing summary statistics
138
        """
139
        pass
140
    
141
    def correlations(self, method='pearson'):
142
        """
143
        Calculate correlations between variables.
144
        
145
        Args:
146
            method: Correlation method ('pearson', 'spearman', 'kendall')
147
            
148
        Returns:
149
            Correlation matrix as pandas DataFrame
150
        """
151
        pass
152

153
# Generate help for the class
154
help_text = helptext.HelpText(DataAnalyzer)
155
print(help_text)
156
```
157

158
**Using Fire's built-in help:**
159
```python
160
import fire
161

162
class Calculator:
163
    """A simple calculator with basic arithmetic operations."""
164
    
165
    def add(self, x, y):
166
        """Add two numbers together."""
167
        return x + y
168
    
169
    def multiply(self, x, y):
170
        """Multiply two numbers.""" 
171
        return x * y
172

173
if __name__ == '__main__':
174
    fire.Fire(Calculator)
175
    # Command line: python calc.py -- --help
176
    # Shows help for the Calculator class
177
    
178
    # Command line: python calc.py add -- --help  
179
    # Shows help for the add method
180
```
181

182
## Help Text Features
183

184
**Automatic signature extraction:**
185
Fire automatically extracts and formats function signatures, including:
186
- Parameter names and types
187
- Default values
188
- Variable arguments (*args, **kwargs)
189
- Type hints and annotations
190

191
**Docstring parsing:**
192
Supports multiple docstring formats:
193
- Google style
194
- NumPy style  
195
- Sphinx style
196
- Plain text descriptions
197

198
**Usage examples:**
199
```bash
200
# Get help for main component
201
python my_cli.py -- --help
202

203
# Get help for specific subcommand  
204
python my_cli.py subcommand -- --help
205

206
# Verbose help with private members
207
python my_cli.py -- --help --verbose
208

209
# Usage information only
210
python my_cli.py -- --usage
211
```
212

213
**Formatted output includes:**
214
- Component name and description
215
- Usage syntax with argument names
216
- Parameter descriptions with types and defaults
217
- Return value information
218
- Exception documentation
219
- Related commands and subcommands
220

221
## Customization
222

223
Fire's help system respects:
224
- **Type hints** for parameter type display
225
- **Docstring conventions** for structured information
226
- **Default values** for optional parameter indication  
227
- **Private member filtering** (unless --verbose is used)
228

229
The help text automatically adapts to the component type:
230
- **Functions**: Show signature and docstring
231
- **Classes**: Show constructor and available methods
232
- **Modules**: Show available functions and classes
233
- **Objects**: Show available attributes and methods