forked from datalad/datalad
-
Notifications
You must be signed in to change notification settings - Fork 0
/
formatters.py
310 lines (251 loc) · 10.2 KB
/
formatters.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
# ## ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
#
# See COPYING file distributed along with the DataLad package for the
# copyright and license terms.
#
# ## ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
import argparse
import datetime
import re
class ManPageFormatter(argparse.HelpFormatter):
# This code was originally distributed
# under the same License of Python
# Copyright (c) 2014 Oz Nahum Tiram <nahumoz@gmail.com>
def __init__(self,
prog,
indent_increment=2,
max_help_position=4,
width=1000000,
section=1,
ext_sections=None,
authors=None,
version=None
):
super(ManPageFormatter, self).__init__(
prog,
indent_increment=indent_increment,
max_help_position=max_help_position,
width=width)
self._prog = prog
self._section = 1
self._today = datetime.date.today().strftime('%Y\\-%m\\-%d')
self._ext_sections = ext_sections
self._version = version
def _get_formatter(self, **kwargs):
return self.formatter_class(prog=self.prog, **kwargs)
def _markup(self, txt):
return txt.replace('-', '\\-')
def _underline(self, string):
return "\\fI\\s-1" + string + "\\s0\\fR"
def _bold(self, string):
if not string.strip().startswith('\\fB'):
string = '\\fB' + string
if not string.strip().endswith('\\fR'):
string = string + '\\fR'
return string
def _mk_synopsis(self, parser):
self.add_usage(parser.usage, parser._actions,
parser._mutually_exclusive_groups, prefix='')
usage = self._format_usage(None, parser._actions,
parser._mutually_exclusive_groups, '')
# replace too long list of commands with a single placeholder
usage = re.sub(r'{[^]]*?create,.*?}', ' COMMAND ', usage, flags=re.MULTILINE)
# take care of proper wrapping
usage = re.sub(r'\[([-a-zA-Z0-9]*)\s([a-zA-Z0-9{}|_]*)\]', r'[\1\~\2]', usage)
usage = usage.replace('%s ' % self._prog, '')
usage = '.SH SYNOPSIS\n.nh\n.HP\n\\fB%s\\fR %s\n.hy\n' % (self._markup(self._prog),
usage)
return usage
def _mk_title(self, prog):
name_version = "\"{0} {1}\"".format(prog, self._version)
return '.TH {0} {1} {2} {3}\n'.format(prog, self._section,
self._today, name_version)
def _make_name(self, parser):
"""
this method is in consitent with others ... it relies on
distribution
"""
return '.SH NAME\n%s \\- %s\n' % (parser.prog,
parser.description)
def _mk_description(self, parser):
desc = parser.description
if not desc:
return ''
desc = desc.replace('\n\n', '\n.PP\n')
# sub-section headings
desc = re.sub(r'^\*(.*)\*$', r'.SS \1', desc, flags=re.MULTILINE)
# italic commands
desc = re.sub(r'^ ([-a-z]*)$', r'.TP\n\\fI\1\\fR', desc, flags=re.MULTILINE)
# deindent body text, leave to troff viewer
desc = re.sub(r'^ (\S.*)\n', '\\1\n', desc, flags=re.MULTILINE)
# format NOTEs as indented paragraphs
desc = re.sub(r'^NOTE\n', '.TP\nNOTE\n', desc, flags=re.MULTILINE)
# deindent indented paragraphs after heading setup
desc = re.sub(r'^ (.*)$', '\\1', desc, flags=re.MULTILINE)
return '.SH DESCRIPTION\n%s\n' % self._markup(desc)
def _mk_footer(self, sections):
if not hasattr(sections, '__iter__'):
return ''
footer = []
for section, value in sections.items():
part = ".SH {}\n {}".format(section.upper(), value)
footer.append(part)
return '\n'.join(footer)
def format_man_page(self, parser):
page = []
page.append(self._mk_title(self._prog))
page.append(self._mk_synopsis(parser))
page.append(self._mk_description(parser))
page.append(self._mk_options(parser))
page.append(self._mk_footer(self._ext_sections))
return ''.join(page)
def _mk_options(self, parser):
formatter = parser._get_formatter()
# positionals, optionals and user-defined groups
for action_group in parser._action_groups:
formatter.start_section(None)
formatter.add_text(None)
formatter.add_arguments(action_group._group_actions)
formatter.end_section()
# epilog
formatter.add_text(parser.epilog)
# determine help from format above
help = formatter.format_help()
# add spaces after comma delimiters for easier reformatting
help = re.sub(r'([a-z]),([a-z])', '\\1, \\2', help)
# get proper indentation for argument items
help = re.sub(r'^ (\S.*)\n', '.TP\n\\1\n', help, flags=re.MULTILINE)
# deindent body text, leave to troff viewer
help = re.sub(r'^ (\S.*)\n', '\\1\n', help, flags=re.MULTILINE)
return '.SH OPTIONS\n' + help
def _format_action_invocation(self, action):
if not action.option_strings:
metavar, = self._metavar_formatter(action, action.dest)(1)
return metavar
else:
parts = []
# if the Optional doesn't take a value, format is:
# -s, --long
if action.nargs == 0:
parts.extend([self._bold(action_str) for action_str in
action.option_strings])
# if the Optional takes a value, format is:
# -s ARGS, --long ARGS
else:
default = self._underline(action.dest.upper())
args_string = self._format_args(action, default)
for option_string in action.option_strings:
parts.append('%s %s' % (self._bold(option_string),
args_string))
return ', '.join(parts)
class RSTManPageFormatter(ManPageFormatter):
def _get_formatter(self, **kwargs):
return self.formatter_class(prog=self.prog, **kwargs)
def _markup(self, txt):
# put general tune-ups here
return txt
def _underline(self, string):
return "*{0}*".format(string)
def _bold(self, string):
return "**{0}**".format(string)
def _mk_synopsis(self, parser):
self.add_usage(parser.usage, parser._actions,
parser._mutually_exclusive_groups, prefix='')
usage = self._format_usage(None, parser._actions,
parser._mutually_exclusive_groups, '')
usage = usage.replace('%s ' % self._prog, '')
usage = 'Synopsis\n--------\n::\n\n %s %s\n' \
% (self._markup(self._prog), usage)
return usage
def _mk_title(self, prog):
# and an easy to use reference point
title = ".. _man_%s:\n\n" % prog
title += "{0}".format(prog)
title += '\n{0}\n\n'.format('=' * len(prog))
return title
def _make_name(self, parser):
return ''
def _mk_description(self, parser):
desc = parser.description
if not desc:
return ''
return 'Description\n-----------\n%s\n' % self._markup(desc)
def _mk_footer(self, sections):
if not hasattr(sections, '__iter__'):
return ''
footer = []
for section, value in sections.items():
part = "\n{0}\n{1}\n{2}\n".format(
section,
'-' * len(section),
value)
footer.append(part)
return '\n'.join(footer)
def _mk_options(self, parser):
# this non-obvious maneuver is really necessary!
formatter = self.__class__(self._prog)
# positionals, optionals and user-defined groups
for action_group in parser._action_groups:
formatter.start_section(None)
formatter.add_text(None)
formatter.add_arguments(action_group._group_actions)
formatter.end_section()
# epilog
formatter.add_text(parser.epilog)
# determine help from format above
option_sec = formatter.format_help()
return '\n\nOptions\n-------\n{0}'.format(option_sec)
def _format_action(self, action):
# determine the required width and the entry label
action_header = self._format_action_invocation(action)
if action.help:
help_text = self._expand_help(action)
help_lines = self._split_lines(help_text, 80)
help = ' '.join(help_lines)
else:
help = ''
# return a single string
return '{0}\n{1}\n{2}\n\n'.format(
action_header,
'~' * len(action_header),
help)
def cmdline_example_to_rst(src, out=None, ref=None):
if out is None:
from six.moves import StringIO
out = StringIO()
# place header
out.write('.. AUTO-GENERATED FILE -- DO NOT EDIT!\n\n')
if ref:
# place cross-ref target
out.write('.. {0}:\n\n'.format(ref))
# parser status vars
inexample = False
incodeblock = False
for line in src:
if line.startswith('#% EXAMPLE START'):
inexample = True
incodeblock = False
continue
if not inexample:
continue
if line.startswith('#% EXAMPLE END'):
break
if not inexample:
continue
if line.startswith('#%'):
incodeblock = not incodeblock
if incodeblock:
out.write('\n.. code-block:: sh\n\n')
continue
if not incodeblock and line.startswith('#'):
out.write(line[(min(2, len(line) - 1)):])
continue
if incodeblock:
if not line.rstrip().endswith('#% SKIP'):
out.write(' %s' % line)
continue
if not len(line.strip()):
continue
else:
raise RuntimeError("this should not happen")
return out