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