277
def get_help_text(self, additional_see_also=None):
277
def get_help_text(self, additional_see_also=None, plain=True):
278
278
"""Return a text string with help for this command.
280
280
:param additional_see_also: Additional help topics to be
281
281
cross-referenced.
282
:param plain: if False, raw help (reStructuredText) is
283
returned instead of plain text.
283
285
doc = self.help()
285
287
raise NotImplementedError("sorry, no detailed help yet for %r" % self.name())
289
# Extract the summary (purpose) and sections out from the text
290
purpose,sections = self._get_help_parts(doc)
292
# If a custom usage section was provided, use it
293
if sections.has_key('Usage'):
294
usage = sections.pop('Usage')
296
usage = self._usage()
298
# The header is the purpose and usage
288
result += 'usage: %s\n' % self._usage()
300
result += ':Purpose: %s\n' % purpose
301
if usage.find('\n') >= 0:
302
result += ':Usage:\n%s\n' % usage
304
result += ':Usage: %s\n' % usage
308
options = option.get_optparser(self.options()).format_option_help()
309
if options.startswith('Options:'):
310
result += ':' + options
315
# Add the description, indenting it 2 spaces
316
# to match the indentation of the options
317
if sections.has_key(None):
318
text = sections.pop(None)
319
text = '\n '.join(text.splitlines())
320
result += ':%s:\n %s\n\n' % ('Description',text)
322
# Add the custom sections (e.g. Examples). Note that there's no need
323
# to indent these as they must be indented already in the source.
325
labels = sorted(sections.keys())
327
result += ':%s:\n%s\n\n' % (label,sections[label])
329
# Add the aliases, source (plug-in) and see also links, if any
291
result += 'aliases: '
331
result += ':Aliases: '
292
332
result += ', '.join(self.aliases) + '\n'
296
333
plugin_name = self.plugin_name()
297
334
if plugin_name is not None:
298
result += '(From plugin "%s")' % plugin_name
302
if result[-1] != '\n':
305
result += option.get_optparser(self.options()).format_option_help()
335
result += ':From: plugin "%s"\n' % plugin_name
306
336
see_also = self.get_see_also(additional_see_also)
308
result += '\nSee also: '
309
result += ', '.join(see_also)
338
result += ':See also: '
339
result += ', '.join(see_also) + '\n'
341
# If this will be rendered as plan text, convert it
343
import bzrlib.help_topics
344
result = bzrlib.help_topics.help_as_plain_text(result)
348
def _get_help_parts(text):
349
"""Split help text into a summary and named sections.
351
:return: (summary,sections) where summary is the top line and
352
sections is a dictionary of the rest indexed by section name.
353
A section starts with a heading line of the form ":xxx:".
354
Indented text on following lines is the section value.
355
All text found outside a named section is assigned to the
356
default section which is given the key of None.
358
def save_section(sections, label, section):
360
if sections.has_key(label):
361
sections[label] += '\n' + section
363
sections[label] = section
365
lines = text.rstrip().splitlines()
366
summary = lines.pop(0)
368
label,section = None,''
370
if line.startswith(':') and line.endswith(':') and len(line) > 2:
371
save_section(sections, label, section)
372
label,section = line[1:-1],''
373
elif label != None and len(line) > 1 and not line[0].isspace():
374
save_section(sections, label, section)
375
label,section = None,line
378
section += '\n' + line
381
save_section(sections, label, section)
382
return summary, sections
313
384
def get_help_topic(self):
314
385
"""Return the commands help topic - its name."""
315
386
return self.name()