277
def get_help_text(self, additional_see_also=None):
277
def get_help_text(self, additional_see_also=None, plain=True,
278
see_also_as_links=False):
278
279
"""Return a text string with help for this command.
280
281
:param additional_see_also: Additional help topics to be
281
282
cross-referenced.
283
:param plain: if False, raw help (reStructuredText) is
284
returned instead of plain text.
285
:param see_also_as_links: if True, convert items in 'See also'
286
list to internal links (used by bzr_man rstx generator)
283
288
doc = self.help()
285
290
raise NotImplementedError("sorry, no detailed help yet for %r" % self.name())
292
# Extract the summary (purpose) and sections out from the text
293
purpose,sections = self._get_help_parts(doc)
295
# If a custom usage section was provided, use it
296
if sections.has_key('Usage'):
297
usage = sections.pop('Usage')
299
usage = self._usage()
301
# The header is the purpose and usage
288
result += 'usage: %s\n' % self._usage()
303
result += ':Purpose: %s\n' % purpose
304
if usage.find('\n') >= 0:
305
result += ':Usage:\n%s\n' % usage
307
result += ':Usage: %s\n' % usage
311
options = option.get_optparser(self.options()).format_option_help()
312
if options.startswith('Options:'):
313
result += ':' + options
314
elif options.startswith('options:'):
315
# Python 2.4 version of optparse
316
result += ':Options:' + options[len('options:'):]
321
# Add the description, indenting it 2 spaces
322
# to match the indentation of the options
323
if sections.has_key(None):
324
text = sections.pop(None)
325
text = '\n '.join(text.splitlines())
326
result += ':%s:\n %s\n\n' % ('Description',text)
328
# Add the custom sections (e.g. Examples). Note that there's no need
329
# to indent these as they must be indented already in the source.
331
labels = sorted(sections.keys())
333
result += ':%s:\n%s\n\n' % (label,sections[label])
335
# Add the aliases, source (plug-in) and see also links, if any
291
result += 'aliases: '
337
result += ':Aliases: '
292
338
result += ', '.join(self.aliases) + '\n'
296
339
plugin_name = self.plugin_name()
297
340
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()
341
result += ':From: plugin "%s"\n' % plugin_name
306
342
see_also = self.get_see_also(additional_see_also)
308
result += '\nSee also: '
309
result += ', '.join(see_also)
344
if not plain and see_also_as_links:
346
for item in see_also:
348
# topics doesn't have an independent section
349
# so don't create a real link
350
see_also_links.append(item)
352
# Use a reST link for this entry
353
see_also_links.append("`%s`_" % (item,))
354
see_also = see_also_links
355
result += ':See also: '
356
result += ', '.join(see_also) + '\n'
358
# If this will be rendered as plan text, convert it
360
import bzrlib.help_topics
361
result = bzrlib.help_topics.help_as_plain_text(result)
365
def _get_help_parts(text):
366
"""Split help text into a summary and named sections.
368
:return: (summary,sections) where summary is the top line and
369
sections is a dictionary of the rest indexed by section name.
370
A section starts with a heading line of the form ":xxx:".
371
Indented text on following lines is the section value.
372
All text found outside a named section is assigned to the
373
default section which is given the key of None.
375
def save_section(sections, label, section):
377
if sections.has_key(label):
378
sections[label] += '\n' + section
380
sections[label] = section
382
lines = text.rstrip().splitlines()
383
summary = lines.pop(0)
385
label,section = None,''
387
if line.startswith(':') and line.endswith(':') and len(line) > 2:
388
save_section(sections, label, section)
389
label,section = line[1:-1],''
390
elif label != None and len(line) > 1 and not line[0].isspace():
391
save_section(sections, label, section)
392
label,section = None,line
395
section += '\n' + line
398
save_section(sections, label, section)
399
return summary, sections
313
401
def get_help_topic(self):
314
402
"""Return the commands help topic - its name."""
315
403
return self.name()
317
405
def get_see_also(self, additional_terms=None):
318
"""Return a list of help topics that are related to this ommand.
406
"""Return a list of help topics that are related to this command.
320
408
The list is derived from the content of the _see_also attribute. Any
321
409
duplicates are removed and the result is in lexical order.
added
removed
bzrlib/commands.py
