# help.py - help data for mercurial
#
# Copyright 2006 Matt Mackall <mpm@selenic.com>
#
# This software may be used and distributed according to the terms of the
# GNU General Public License version 2 or any later version.
from __future__ import absolute_import
import itertools
import os
import textwrap
from .i18n import (
_,
gettext,
)
from . import (
cmdutil,
encoding,
error,
extensions,
fancyopts,
filemerge,
fileset,
minirst,
pycompat,
revset,
templatefilters,
templatefuncs,
templatekw,
util,
)
from .hgweb import (
webcommands,
)
_exclkeywords = {
"(ADVANCED)",
"(DEPRECATED)",
"(EXPERIMENTAL)",
# i18n: "(ADVANCED)" is a keyword, must be translated consistently
_("(ADVANCED)"),
# i18n: "(DEPRECATED)" is a keyword, must be translated consistently
_("(DEPRECATED)"),
# i18n: "(EXPERIMENTAL)" is a keyword, must be translated consistently
_("(EXPERIMENTAL)"),
}
def listexts(header, exts, indent=1, showdeprecated=False):
'''return a text listing of the given extensions'''
rst = []
if exts:
for name, desc in sorted(exts.iteritems()):
if not showdeprecated and any(w in desc for w in _exclkeywords):
continue
rst.append('%s:%s: %s\n' % (' ' * indent, name, desc))
if rst:
rst.insert(0, '\n%s\n\n' % header)
return rst
def extshelp(ui):
rst = loaddoc('extensions')(ui).splitlines(True)
rst.extend(listexts(
_('enabled extensions:'), extensions.enabled(), showdeprecated=True))
rst.extend(listexts(_('disabled extensions:'), extensions.disabled(),
showdeprecated=ui.verbose))
doc = ''.join(rst)
return doc
def optrst(header, options, verbose):
data = []
multioccur = False
for option in options:
if len(option) == 5:
shortopt, longopt, default, desc, optlabel = option
else:
shortopt, longopt, default, desc = option
optlabel = _("VALUE") # default label
if not verbose and any(w in desc for w in _exclkeywords):
continue
so = ''
if shortopt:
so = '-' + shortopt
lo = '--' + longopt
if isinstance(default, fancyopts.customopt):
default = default.getdefaultvalue()
if default and not callable(default):
# default is of unknown type, and in Python 2 we abused
# the %s-shows-repr property to handle integers etc. To
# match that behavior on Python 3, we do str(default) and
# then convert it to bytes.
desc += _(" (default: %s)") % pycompat.bytestr(default)
if isinstance(default, list):
lo += " %s [+]" % optlabel
multioccur = True
elif (default is not None) and not isinstance(default, bool):
lo += " %s" % optlabel
data.append((so, lo, desc))
if multioccur:
header += (_(" ([+] can be repeated)"))
rst = ['\n%s:\n\n' % header]
rst.extend(minirst.maketable(data, 1))
return ''.join(rst)
def indicateomitted(rst, omitted, notomitted=None):
rst.append('\n\n.. container:: omitted\n\n %s\n\n' % omitted)
if notomitted:
rst.append('\n\n.. container:: notomitted\n\n %s\n\n' % notomitted)
def filtercmd(ui, cmd, kw, doc):
if not ui.debugflag and cmd.startswith("debug") and kw != "debug":
return True
if not ui.verbose and doc and any(w in doc for w in _exclkeywords):
return True
return False
def topicmatch(ui, commands, kw):
"""Return help topics matching kw.
Returns {'section': [(name, summary), ...], ...} where section is
one of topics, commands, extensions, or extensioncommands.
"""
kw = encoding.lower(kw)
def lowercontains(container):
return kw in encoding.lower(container) # translated in helptable
results = {'topics': [],
'commands': [],
'extensions': [],
'extensioncommands': [],
}
for names, header, doc in helptable:
# Old extensions may use a str as doc.
if (sum(map(lowercontains, names))
or lowercontains(header)
or (callable(doc) and lowercontains(doc(ui)))):
results['topics'].append((names[0], header))
for cmd, entry in commands.table.iteritems():
if len(entry) == 3:
summary = entry[2]
else:
summary = ''
# translate docs *before* searching there
docs = _(pycompat.getdoc(entry[0])) or ''
if kw in cmd or lowercontains(summary) or lowercontains(docs):
doclines = docs.splitlines()
if doclines:
summary = doclines[0]
cmdname = cmdutil.parsealiases(cmd)[0]
if filtercmd(ui, cmdname, kw, docs):
continue
results['commands'].append((cmdname, summary))
for name, docs in itertools.chain(
extensions.enabled(False).iteritems(),
extensions.disabled().iteritems()):
if not docs:
continue
name = name.rpartition('.')[-1]
if lowercontains(name) or lowercontains(docs):
# extension docs are already translated
results['extensions'].append((name, docs.splitlines()[0]))
try:
mod = extensions.load(ui, name, '')
except ImportError:
# debug message would be printed in extensions.load()
continue
for cmd, entry in getattr(mod, 'cmdtable', {}).iteritems():
if kw in cmd or (len(entry) > 2 and lowercontains(entry[2])):
cmdname = cmdutil.parsealiases(cmd)[0]
cmddoc = pycompat.getdoc(entry[0])
if cmddoc:
cmddoc = gettext(cmddoc).splitlines()[0]
else:
cmddoc = _('(no help text available)')
if filtercmd(ui, cmdname, kw, cmddoc):
continue
results['extensioncommands'].append((cmdname, cmddoc))
return results
def loaddoc(topic, subdir=None):
"""Return a delayed loader for help/topic.txt."""
def loader(ui):
docdir = os.path.join(util.datapath, 'help')
if subdir:
docdir = os.path.join(docdir, subdir)
path = os.path.join(docdir, topic + ".txt")
doc = gettext(util.readfile(path))
for rewriter in helphooks.get(topic, []):
doc = rewriter(ui, topic, doc)
return doc
return loader
internalstable = sorted([
(['bundle2'], _('Bundle2'),
loaddoc('bundle2', subdir='internals')),
(['bundles'], _('Bundles'),
loaddoc('bundles', subdir='internals')),
(['censor'], _('Censor'),
loaddoc('censor', subdir='internals')),
(['changegroups'], _('Changegroups'),
loaddoc('changegroups', subdir='internals')),
(['config'], _('Config Registrar'),
loaddoc('config', subdir='internals')),
(['requirements'], _('Repository Requirements'),
loaddoc('requirements', subdir='internals')),
(['revlogs'], _('Revision Logs'),
loaddoc('revlogs', subdir='internals')),
(['wireprotocol'], _('Wire Protocol'),
loaddoc('wireprotocol', subdir='internals')),
])
def internalshelp(ui):
"""Generate the index for the "internals" topic."""
lines = ['To access a subtopic, use "hg help internals.{subtopic-name}"\n',
'\n']
for names, header, doc in internalstable:
lines.append(' :%s: %s\n' % (names[0], header))
return ''.join(lines)
helptable = sorted([
(['bundlespec'], _("Bundle File Formats"), loaddoc('bundlespec')),
(['color'], _("Colorizing Outputs"), loaddoc('color')),
(["config", "hgrc"], _("Configuration Files"), loaddoc('config')),
(['deprecated'], _("Deprecated Features"), loaddoc('deprecated')),
(["dates"], _("Date Formats"), loaddoc('dates')),
(["flags"], _("Command-line flags"), loaddoc('flags')),
(["patterns"], _("File Name Patterns"), loaddoc('patterns')),
(['environment', 'env'], _('Environment Variables'),
loaddoc('environment')),
(['revisions', 'revs', 'revsets', 'revset', 'multirevs', 'mrevs'],
_('Specifying Revisions'), loaddoc('revisions')),
(['filesets', 'fileset'], _("Specifying File Sets"), loaddoc('filesets')),
(['diffs'], _('Diff Formats'), loaddoc('diffs')),
(['merge-tools', 'mergetools', 'mergetool'], _('Merge Tools'),
loaddoc('merge-tools')),
(['templating', 'templates', 'template', 'style'], _('Template Usage'),
loaddoc('templates')),
(['urls'], _('URL Paths'), loaddoc('urls')),
(["extensions"], _("Using Additional Features"), extshelp),
(["subrepos", "subrepo"], _("Subrepositories"), loaddoc('subrepos')),
(["hgweb"], _("Configuring hgweb"), loaddoc('hgweb')),
(["glossary"], _("Glossary"), loaddoc('glossary')),
(["hgignore", "ignore"], _("Syntax for Mercurial Ignore Files"),
loaddoc('hgignore')),
(["phases"], _("Working with Phases"), loaddoc('phases')),
(['scripting'], _('Using Mercurial from scripts and automation'),
loaddoc('scripting')),
(['internals'], _("Technical implementation topics"),
internalshelp),
(['pager'], _("Pager Support"), loaddoc('pager')),
])
# Maps topics with sub-topics to a list of their sub-topics.
subtopics = {
'internals': internalstable,
}
# Map topics to lists of callable taking the current topic help and
# returning the updated version
helphooks = {}
def addtopichook(topic, rewriter):
helphooks.setdefault(topic, []).append(rewriter)
def makeitemsdoc(ui, topic, doc, marker, items, dedent=False):
"""Extract docstring from the items key to function mapping, build a
single documentation block and use it to overwrite the marker in doc.
"""
entries = []
for name in sorted(items):
text = (pycompat.getdoc(items[name]) or '').rstrip()
if (not text
or not ui.verbose and any(w in text for w in _exclkeywords)):
continue
text = gettext(text)
if dedent:
# Abuse latin1 to use textwrap.dedent() on bytes.
text = textwrap.dedent(text.decode('latin1')).encode('latin1')
lines = text.splitlines()
doclines = [(lines[0])]
for l in lines[1:]:
# Stop once we find some Python doctest
if l.strip().startswith('>>>'):
break
if dedent:
doclines.append(l.rstrip())
else:
doclines.append(' ' + l.strip())
entries.append('\n'.join(doclines))
entries = '\n\n'.join(entries)
return doc.replace(marker, entries)
def addtopicsymbols(topic, marker, symbols, dedent=False):
def add(ui, topic, doc):
return makeitemsdoc(ui, topic, doc, marker, symbols, dedent=dedent)
addtopichook(topic, add)
addtopicsymbols('bundlespec', '.. bundlecompressionmarker',
util.bundlecompressiontopics())
addtopicsymbols('filesets', '.. predicatesmarker', fileset.symbols)
addtopicsymbols('merge-tools', '.. internaltoolsmarker',
filemerge.internalsdoc)
addtopicsymbols('revisions', '.. predicatesmarker', revset.symbols)
addtopicsymbols('templates', '.. keywordsmarker', templatekw.keywords)
addtopicsymbols('templates', '.. filtersmarker', templatefilters.filters)
addtopicsymbols('templates', '.. functionsmarker', templatefuncs.funcs)
addtopicsymbols('hgweb', '.. webcommandsmarker', webcommands.commands,
dedent=True)
def help_(ui, commands, name, unknowncmd=False, full=True, subtopic=None,
**opts):
'''
Generate the help for 'name' as unformatted restructured text. If
'name' is None, describe the commands available.
'''
opts = pycompat.byteskwargs(opts)
def helpcmd(name, subtopic=None):
try:
aliases, entry = cmdutil.findcmd(name, commands.table,
strict=unknowncmd)
except error.AmbiguousCommand as inst:
# py3k fix: except vars can't be used outside the scope of the
# except block, nor can be used inside a lambda. python issue4617
prefix = inst.args[0]
select = lambda c: cmdutil.parsealiases(c)[0].startswith(prefix)
rst = helplist(select)
return rst
rst = []
# check if it's an invalid alias and display its error if it is
if getattr(entry[0], 'badalias', None):
rst.append(entry[0].badalias + '\n')
if entry[0].unknowncmd:
try:
rst.extend(helpextcmd(entry[0].cmdname))
except error.UnknownCommand:
pass
return rst
# synopsis
if len(entry) > 2:
if entry[2].startswith('hg'):
rst.append("%s\n" % entry[2])
else:
rst.append('hg %s %s\n' % (aliases[0], entry[2]))
else:
rst.append('hg %s\n' % aliases[0])
# aliases
if full and not ui.quiet and len(aliases) > 1:
rst.append(_("\naliases: %s\n") % ', '.join(aliases[1:]))
rst.append('\n')
# description
doc = gettext(pycompat.getdoc(entry[0]))
if not doc:
doc = _("(no help text available)")
if util.safehasattr(entry[0], 'definition'): # aliased command
source = entry[0].source
if entry[0].definition.startswith('!'): # shell alias
doc = (_('shell alias for: %s\n\n%s\n\ndefined by: %s\n') %
(entry[0].definition[1:], doc, source))
else:
doc = (_('alias for: hg %s\n\n%s\n\ndefined by: %s\n') %
(entry[0].definition, doc, source))
doc = doc.splitlines(True)
if ui.quiet or not full:
rst.append(doc[0])
else:
rst.extend(doc)
rst.append('\n')
# check if this command shadows a non-trivial (multi-line)
# extension help text
try:
mod = extensions.find(name)
doc = gettext(pycompat.getdoc(mod)) or ''
if '\n' in doc.strip():
msg = _("(use 'hg help -e %s' to show help for "
"the %s extension)") % (name, name)
rst.append('\n%s\n' % msg)
except KeyError:
pass
# options
if not ui.quiet and entry[1]:
rst.append(optrst(_("options"), entry[1], ui.verbose))
if ui.verbose:
rst.append(optrst(_("global options"),
commands.globalopts, ui.verbose))
if not ui.verbose:
if not full:
rst.append(_("\n(use 'hg %s -h' to show more help)\n")
% name)
elif not ui.quiet:
rst.append(_('\n(some details hidden, use --verbose '
'to show complete help)'))
return rst
def helplist(select=None, **opts):
# list of commands
if name == "shortlist":
header = _('basic commands:\n\n')
elif name == "debug":
header = _('debug commands (internal and unsupported):\n\n')
else:
header = _('list of commands:\n\n')
h = {}
cmds = {}
for c, e in commands.table.iteritems():
fs = cmdutil.parsealiases(c)
f = fs[0]
p = ''
if c.startswith("^"):
p = '^'
if select and not select(p + f):
continue
if (not select and name != 'shortlist' and
e[0].__module__ != commands.__name__):
continue
if name == "shortlist" and not p:
continue
doc = pycompat.getdoc(e[0])
if filtercmd(ui, f, name, doc):
continue
doc = gettext(doc)
if not doc:
doc = _("(no help text available)")
h[f] = doc.splitlines()[0].rstrip()
cmds[f] = '|'.join(fs)
rst = []
if not h:
if not ui.quiet:
rst.append(_('no commands defined\n'))
return rst
if not ui.quiet:
rst.append(header)
fns = sorted(h)
for f in fns:
if ui.verbose:
commacmds = cmds[f].replace("|",", ")
rst.append(" :%s: %s\n" % (commacmds, h[f]))
else:
rst.append(' :%s: %s\n' % (f, h[f]))
ex = opts.get
anyopts = (ex(r'keyword') or not (ex(r'command') or ex(r'extension')))
if not name and anyopts:
exts = listexts(_('enabled extensions:'), extensions.enabled())
if exts:
rst.append('\n')
rst.extend(exts)
rst.append(_("\nadditional help topics:\n\n"))
topics = []
for names, header, doc in helptable:
topics.append((names[0], header))
for t, desc in topics:
rst.append(" :%s: %s\n" % (t, desc))
if ui.quiet:
pass
elif ui.verbose:
rst.append('\n%s\n' % optrst(_("global options"),
commands.globalopts, ui.verbose))
if name == 'shortlist':
rst.append(_("\n(use 'hg help' for the full list "
"of commands)\n"))
else:
if name == 'shortlist':
rst.append(_("\n(use 'hg help' for the full list of commands "
"or 'hg -v' for details)\n"))
elif name and not full:
rst.append(_("\n(use 'hg help %s' to show the full help "
"text)\n") % name)
elif name and cmds and name in cmds.keys():
rst.append(_("\n(use 'hg help -v -e %s' to show built-in "
"aliases and global options)\n") % name)
else:
rst.append(_("\n(use 'hg help -v%s' to show built-in aliases "
"and global options)\n")
% (name and " " + name or ""))
return rst
def helptopic(name, subtopic=None):
# Look for sub-topic entry first.
header, doc = None, None
if subtopic and name in subtopics:
for names, header, doc in subtopics[name]:
if subtopic in names:
break
if not header:
for names, header, doc in helptable:
if name in names:
break
else:
raise error.UnknownCommand(name)
rst = [minirst.section(header)]
# description
if not doc:
rst.append(" %s\n" % _("(no help text available)"))
if callable(doc):
rst += [" %s\n" % l for l in doc(ui).splitlines()]
if not ui.verbose:
omitted = _('(some details hidden, use --verbose'
' to show complete help)')
indicateomitted(rst, omitted)
try:
cmdutil.findcmd(name, commands.table)
rst.append(_("\nuse 'hg help -c %s' to see help for "
"the %s command\n") % (name, name))
except error.UnknownCommand:
pass
return rst
def helpext(name, subtopic=None):
try:
mod = extensions.find(name)
doc = gettext(pycompat.getdoc(mod)) or _('no help text available')
except KeyError:
mod = None
doc = extensions.disabledext(name)
if not doc:
raise error.UnknownCommand(name)
if '\n' not in doc:
head, tail = doc, ""
else:
head, tail = doc.split('\n', 1)
rst = [_('%s extension - %s\n\n') % (name.rpartition('.')[-1], head)]
if tail:
rst.extend(tail.splitlines(True))
rst.append('\n')
if not ui.verbose:
omitted = _('(some details hidden, use --verbose'
' to show complete help)')
indicateomitted(rst, omitted)
if mod:
try:
ct = mod.cmdtable
except AttributeError:
ct = {}
modcmds = set([c.partition('|')[0] for c in ct])
rst.extend(helplist(modcmds.__contains__))
else:
rst.append(_("(use 'hg help extensions' for information on enabling"
" extensions)\n"))
return rst
def helpextcmd(name, subtopic=None):
cmd, ext, doc = extensions.disabledcmd(ui, name,
ui.configbool('ui', 'strict'))
doc = doc.splitlines()[0]
rst = listexts(_("'%s' is provided by the following "
"extension:") % cmd, {ext: doc}, indent=4,
showdeprecated=True)
rst.append('\n')
rst.append(_("(use 'hg help extensions' for information on enabling "
"extensions)\n"))
return rst
rst = []
kw = opts.get('keyword')
if kw or name is None and any(opts[o] for o in opts):
matches = topicmatch(ui, commands, name or '')
helpareas = []
if opts.get('extension'):
helpareas += [('extensions', _('Extensions'))]
if opts.get('command'):
helpareas += [('commands', _('Commands'))]
if not helpareas:
helpareas = [('topics', _('Topics')),
('commands', _('Commands')),
('extensions', _('Extensions')),
('extensioncommands', _('Extension Commands'))]
for t, title in helpareas:
if matches[t]:
rst.append('%s:\n\n' % title)
rst.extend(minirst.maketable(sorted(matches[t]), 1))
rst.append('\n')
if not rst:
msg = _('no matches')
hint = _("try 'hg help' for a list of topics")
raise error.Abort(msg, hint=hint)
elif name and name != 'shortlist':
queries = []
if unknowncmd:
queries += [helpextcmd]
if opts.get('extension'):
queries += [helpext]
if opts.get('command'):
queries += [helpcmd]
if not queries:
queries = (helptopic, helpcmd, helpext, helpextcmd)
for f in queries:
try:
rst = f(name, subtopic)
break
except error.UnknownCommand:
pass
else:
if unknowncmd:
raise error.UnknownCommand(name)
else:
msg = _('no such help topic: %s') % name
hint = _("try 'hg help --keyword %s'") % name
raise error.Abort(msg, hint=hint)
else:
# program name
if not ui.quiet:
rst = [_("Mercurial Distributed SCM\n"), '\n']
rst.extend(helplist(None, **pycompat.strkwargs(opts)))
return ''.join(rst)
def formattedhelp(ui, commands, name, keep=None, unknowncmd=False, full=True,
**opts):
"""get help for a given topic (as a dotted name) as rendered rst
Either returns the rendered help text or raises an exception.
"""
if keep is None:
keep = []
else:
keep = list(keep) # make a copy so we can mutate this later
fullname = name
section = None
subtopic = None
if name and '.' in name:
name, remaining = name.split('.', 1)
remaining = encoding.lower(remaining)
if '.' in remaining:
subtopic, section = remaining.split('.', 1)
else:
if name in subtopics:
subtopic = remaining
else:
section = remaining
textwidth = ui.configint('ui', 'textwidth')
termwidth = ui.termwidth() - 2
if textwidth <= 0 or termwidth < textwidth:
textwidth = termwidth
text = help_(ui, commands, name,
subtopic=subtopic, unknowncmd=unknowncmd, full=full, **opts)
formatted, pruned = minirst.format(text, textwidth, keep=keep,
section=section)
# We could have been given a weird ".foo" section without a name
# to look for, or we could have simply failed to found "foo.bar"
# because bar isn't a section of foo
if section and not (formatted and name):
raise error.Abort(_("help section not found: %s") % fullname)
if 'verbose' in pruned:
keep.append('omitted')
else:
keep.append('notomitted')
formatted, pruned = minirst.format(text, textwidth, keep=keep,
section=section)
return formatted