0
# Command Line Interface
1

2
Command-line tools for file-based markup conversion with support for different text encodings and batch processing. python-creole provides several CLI commands for converting files between markup formats.
3

4
## Capabilities
5

6
### CLI Framework
7

8
Base class for command-line conversion tools.
9

10
```python { .api }
11
class CreoleCLI:
12
    def __init__(self, convert_func): ...
13
    def convert(self, sourcefile: str, destination: str, encoding: str): ...
14
```
15

16
**Parameters:**
17
- `convert_func`: Conversion function to use (creole2html, html2creole, etc.)
18

19
**Usage Examples:**
20

21
```python
22
from creole.cmdline import CreoleCLI
23
from creole import creole2html
24

25
# Create custom CLI tool
26
cli = CreoleCLI(creole2html)
27
cli.convert('input.creole', 'output.html', 'utf-8')
28
```
29

30
### Command Entry Points
31

32
Pre-configured CLI functions for each conversion type.
33

34
```python { .api }
35
def cli_creole2html(): ...
36
def cli_html2creole(): ...  
37
def cli_html2rest(): ...
38
def cli_html2textile(): ...
39
```
40

41
**Usage Examples:**
42

43
```python
44
# These are called by the installed command-line tools
45
from creole.cmdline import cli_creole2html, cli_html2creole
46

47
# Direct invocation (not typical usage)
48
import sys
49
sys.argv = ['creole2html', 'input.creole', 'output.html']
50
cli_creole2html()
51
```
52

53
## Command Line Tools
54

55
When python-creole is installed, these commands become available:
56

57
### creole2html
58

59
Convert Creole markup files to HTML.
60

61
```bash
62
creole2html input.creole output.html
63
creole2html --encoding=utf-8 source.txt dest.html
64
creole2html --help
65
```
66

67
**Options:**
68
- `sourcefile`: Input Creole file path
69
- `destination`: Output HTML file path  
70
- `--encoding`: Text encoding (default: utf-8)
71
- `--version`: Show version information
72
- `--help`: Show help message
73

74
**Usage Examples:**
75

76
```bash
77
# Basic conversion
78
creole2html README.creole README.html
79

80
# Specify encoding
81
creole2html --encoding=latin1 old_file.creole new_file.html
82

83
# Convert multiple files with shell globbing
84
for file in *.creole; do
85
    creole2html "$file" "${file%.creole}.html"
86
done
87
```
88

89
### html2creole
90

91
Convert HTML files to Creole markup.
92

93
```bash
94
html2creole input.html output.creole
95
html2creole --encoding=utf-8 source.html dest.txt
96
html2creole --help
97
```
98

99
**Options:**
100
- `sourcefile`: Input HTML file path
101
- `destination`: Output Creole file path
102
- `--encoding`: Text encoding (default: utf-8)
103
- `--version`: Show version information
104
- `--help`: Show help message
105

106
**Usage Examples:**
107

108
```bash
109
# Basic conversion
110
html2creole webpage.html content.creole
111

112
# Batch convert HTML files
113
find . -name "*.html" -exec html2creole {} {}.creole \;
114

115
# Convert with specific encoding
116
html2creole --encoding=iso-8859-1 legacy.html modern.creole
117
```
118

119
### html2rest
120

121
Convert HTML files to ReStructuredText.
122

123
```bash
124
html2rest input.html output.rst
125
html2rest --encoding=utf-8 source.html dest.rst
126
html2rest --help
127
```
128

129
**Options:**
130
- `sourcefile`: Input HTML file path
131
- `destination`: Output ReStructuredText file path
132
- `--encoding`: Text encoding (default: utf-8)
133
- `--version`: Show version information
134
- `--help`: Show help message
135

136
**Usage Examples:**
137

138
```bash
139
# Convert for Sphinx documentation
140
html2rest content.html docs/content.rst
141

142
# Convert README for PyPI
143
html2rest README.html README.rst
144

145
# Process documentation files
146
mkdir -p rst_docs
147
for html in docs/*.html; do
148
    html2rest "$html" "rst_docs/$(basename "$html" .html).rst"
149
done
150
```
151

152
### html2textile
153

154
Convert HTML files to Textile markup.
155

156
```bash
157
html2textile input.html output.textile
158
html2textile --encoding=utf-8 source.html dest.txt
159
html2textile --help
160
```
161

162
**Options:**
163
- `sourcefile`: Input HTML file path
164
- `destination`: Output Textile file path
165
- `--encoding`: Text encoding (default: utf-8)
166
- `--version`: Show version information
167
- `--help`: Show help message
168

169
**Usage Examples:**
170

171
```bash
172
# Basic conversion
173
html2textile article.html article.textile
174

175
# Convert blog posts
176
html2textile blog_post.html blog_post.txt
177

178
# Batch process with custom encoding
179
html2textile --encoding=cp1252 windows_file.html output.textile
180
```
181

182
## Additional CLI Tools
183

184
### update_rst_readme
185

186
Update ReStructuredText README from Creole source.
187

188
```bash
189
update_rst_readme
190
```
191

192
**Usage Examples:**
193

194
```bash
195
# Update README.rst from README.creole in current directory
196
cd /my/project
197
update_rst_readme
198

199
# Use in build scripts
200
#!/bin/bash
201
cd "$PROJECT_ROOT"
202
update_rst_readme
203
echo "README.rst updated"
204
```
205

206
### publish
207

208
Publish python-creole package to PyPI (internal tool).
209

210
```bash
211
publish
212
```
213

214
## Error Handling
215

216
All CLI tools provide consistent error handling:
217

218
```bash
219
# File not found
220
$ creole2html nonexistent.creole output.html
221
Error: Could not read input file 'nonexistent.creole'
222

223
# Permission denied
224
$ html2creole input.html /root/output.creole
225
Error: Could not write to output file '/root/output.creole'
226

227
# Encoding errors
228
$ creole2html --encoding=ascii unicode_file.creole output.html
229
Error: Encoding 'ascii' cannot decode input file
230
```
231

232
## Integration Examples
233

234
### Build Scripts
235

236
```bash
237
#!/bin/bash
238
# build_docs.sh
239

240
echo "Converting documentation..."
241

242
# Convert all Creole files to HTML
243
for creole_file in docs/*.creole; do
244
    html_file="${creole_file%.creole}.html"
245
    echo "Converting $creole_file -> $html_file"
246
    creole2html "$creole_file" "$html_file"
247
done
248

249
# Convert HTML to ReStructuredText for Sphinx
250
for html_file in docs/*.html; do
251
    rst_file="sphinx_docs/$(basename "$html_file" .html).rst"
252
    echo "Converting $html_file -> $rst_file"
253
    html2rest "$html_file" "$rst_file"
254
done
255

256
echo "Documentation conversion complete"
257
```
258

259
### Makefile Integration
260

261
```makefile
262
# Makefile
263

264
docs: README.html docs/manual.html
265

266
README.html: README.creole
267
	creole2html README.creole README.html
268

269
docs/manual.html: docs/manual.creole
270
	creole2html docs/manual.creole docs/manual.html
271

272
rst-docs: docs/*.html
273
	mkdir -p rst-docs
274
	for html in docs/*.html; do \
275
		html2rest "$$html" "rst-docs/$$(basename "$$html" .html).rst"; \
276
	done
277

278
clean:
279
	rm -f README.html docs/*.html rst-docs/*.rst
280

281
.PHONY: docs rst-docs clean
282
```
283

284
### CI/CD Pipeline
285

286
```yaml
287
# .github/workflows/docs.yml
288
name: Update Documentation
289

290
on: [push, pull_request]
291

292
jobs:
293
  docs:
294
    runs-on: ubuntu-latest
295
    steps:
296
    - uses: actions/checkout@v2
297
    
298
    - name: Setup Python
299
      uses: actions/setup-python@v2
300
      with:
301
        python-version: '3.9'
302
        
303
    - name: Install python-creole
304
      run: pip install python-creole
305
      
306
    - name: Update README.rst
307
      run: update_rst_readme
308
      
309
    - name: Convert documentation
310
      run: |
311
        creole2html docs/guide.creole docs/guide.html
312
        html2rest docs/guide.html docs/guide.rst
313
        
314
    - name: Commit updated files
315
      run: |
316
        git config --local user.email "action@github.com"
317
        git config --local user.name "GitHub Action"
318
        git add README.rst docs/guide.html docs/guide.rst
319
        git diff --staged --quiet || git commit -m "Update generated documentation"
320
```
321

322
## Performance Considerations
323

324
For large files or batch processing:
325

326
```bash
327
# Process files in parallel with GNU parallel
328
find docs -name "*.creole" | parallel creole2html {} {.}.html
329

330
# Use shell job control for concurrent processing
331
for file in *.creole; do
332
    creole2html "$file" "${file%.creole}.html" &
333
done
334
wait  # Wait for all background jobs to complete
335
```