help: adding support for command categories

Differential Revision: https://phab.mercurial-scm.org/D5065

doc/gendoc.py

@@ -1,228 +1,229 b''
 #!/usr/bin/env python
 """usage: %s DOC ...
 
 where DOC is the name of a document
 """
 
 from __future__ import absolute_import
 
 import os
 import sys
 import textwrap
 
 # This script is executed during installs and may not have C extensions
 # available. Relax C module requirements.
 os.environ['HGMODULEPOLICY'] = 'allow'
 # import from the live mercurial repo
 sys.path.insert(0, "..")
 from mercurial import demandimport; demandimport.enable()
 # Load util so that the locale path is set by i18n.setdatapath() before
 # calling _().
 from mercurial import util
 util.datapath
 from mercurial import (
     commands,
     extensions,
     help,
     minirst,
     ui as uimod,
 )
 from mercurial.i18n import (
     gettext,
     _,
 )
 
 table = commands.table
 globalopts = commands.globalopts
 helptable = help.helptable
 loaddoc = help.loaddoc
 
 def get_desc(docstr):
     if not docstr:
         return "", ""
     # sanitize
     docstr = docstr.strip("\n")
     docstr = docstr.rstrip()
     shortdesc = docstr.splitlines()[0].strip()
 
     i = docstr.find("\n")
     if i != -1:
         desc = docstr[i + 2:]
     else:
         desc = shortdesc
 
     desc = textwrap.dedent(desc)
 
     return (shortdesc, desc)
 
 def get_opts(opts):
     for opt in opts:
         if len(opt) == 5:
             shortopt, longopt, default, desc, optlabel = opt
         else:
             shortopt, longopt, default, desc = opt
             optlabel = _("VALUE")
         allopts = []
         if shortopt:
             allopts.append("-%s" % shortopt)
         if longopt:
             allopts.append("--%s" % longopt)
         if isinstance(default, list):
             allopts[-1] += " <%s[+]>" % optlabel
         elif (default is not None) and not isinstance(default, bool):
             allopts[-1] += " <%s>" % optlabel
         if '\n' in desc:
             # only remove line breaks and indentation
             desc = ' '.join(l.lstrip() for l in desc.split('\n'))
         desc += default and _(" (default: %s)") % default or ""
         yield (", ".join(allopts), desc)
 
 def get_cmd(cmd, cmdtable):
     d = {}
     attr = cmdtable[cmd]
     cmds = cmd.lstrip("^").split("|")
 
     d['cmd'] = cmds[0]
     d['aliases'] = cmd.split("|")[1:]
     d['desc'] = get_desc(gettext(attr[0].__doc__))
     d['opts'] = list(get_opts(attr[1]))
 
     s = 'hg ' + cmds[0]
     if len(attr) > 2:
         if not attr[2].startswith('hg'):
             s += ' ' + attr[2]
         else:
             s = attr[2]
     d['synopsis'] = s.strip()
 
     return d
 
 def showdoc(ui):
     # print options
     ui.write(minirst.section(_("Options")))
     multioccur = False
     for optstr, desc in get_opts(globalopts):
         ui.write("%s\n    %s\n\n" % (optstr, desc))
         if optstr.endswith("[+]>"):
             multioccur = True
     if multioccur:
         ui.write(_("\n[+] marked option can be specified multiple times\n"))
         ui.write("\n")
 
     # print cmds
     ui.write(minirst.section(_("Commands")))
     commandprinter(ui, table, minirst.subsection)
 
     # print help topics
     # The config help topic is included in the hgrc.5 man page.
     helpprinter(ui, helptable, minirst.section, exclude=['config'])
 
     ui.write(minirst.section(_("Extensions")))
     ui.write(_("This section contains help for extensions that are "
                "distributed together with Mercurial. Help for other "
                "extensions is available in the help system."))
     ui.write(("\n\n"
              ".. contents::\n"
              "   :class: htmlonly\n"
              "   :local:\n"
              "   :depth: 1\n\n"))
 
     for extensionname in sorted(allextensionnames()):
         mod = extensions.load(ui, extensionname, None)
         ui.write(minirst.subsection(extensionname))
         ui.write("%s\n\n" % gettext(mod.__doc__))
         cmdtable = getattr(mod, 'cmdtable', None)
         if cmdtable:
             ui.write(minirst.subsubsection(_('Commands')))
             commandprinter(ui, cmdtable, minirst.subsubsubsection)
 
 def showtopic(ui, topic):
     extrahelptable = [
         (["common"], '', loaddoc('common')),
         (["hg.1"], '', loaddoc('hg.1')),
         (["hg-ssh.8"], '', loaddoc('hg-ssh.8')),
         (["hgignore.5"], '', loaddoc('hgignore.5')),
         (["hgrc.5"], '', loaddoc('hgrc.5')),
         (["hgignore.5.gendoc"], '', loaddoc('hgignore')),
         (["hgrc.5.gendoc"], '', loaddoc('config')),
     ]
     helpprinter(ui, helptable + extrahelptable, None, include=[topic])
 
 def helpprinter(ui, helptable, sectionfunc, include=[], exclude=[]):
-    for names, sec, doc in helptable:
+    for h in helptable:
+        names, sec, doc = h[0:3]
         if exclude and names[0] in exclude:
             continue
         if include and names[0] not in include:
             continue
         for name in names:
             ui.write(".. _%s:\n" % name)
         ui.write("\n")
         if sectionfunc:
             ui.write(sectionfunc(sec))
         if callable(doc):
             doc = doc(ui)
         ui.write(doc)
         ui.write("\n")
 
 def commandprinter(ui, cmdtable, sectionfunc):
     h = {}
     for c, attr in cmdtable.items():
         f = c.split("|")[0]
         f = f.lstrip("^")
         h[f] = c
     cmds = h.keys()
     cmds.sort()
 
     for f in cmds:
         if f.startswith("debug"):
             continue
         d = get_cmd(h[f], cmdtable)
         ui.write(sectionfunc(d['cmd']))
         # short description
         ui.write(d['desc'][0])
         # synopsis
         ui.write("::\n\n")
         synopsislines = d['synopsis'].splitlines()
         for line in synopsislines:
             # some commands (such as rebase) have a multi-line
             # synopsis
             ui.write("   %s\n" % line)
         ui.write('\n')
         # description
         ui.write("%s\n\n" % d['desc'][1])
         # options
         opt_output = list(d['opts'])
         if opt_output:
             opts_len = max([len(line[0]) for line in opt_output])
             ui.write(_("Options:\n\n"))
             multioccur = False
             for optstr, desc in opt_output:
                 if desc:
                     s = "%-*s  %s" % (opts_len, optstr, desc)
                 else:
                     s = optstr
                 ui.write("%s\n" % s)
                 if optstr.endswith("[+]>"):
                     multioccur = True
             if multioccur:
                 ui.write(_("\n[+] marked option can be specified"
                            " multiple times\n"))
             ui.write("\n")
         # aliases
         if d['aliases']:
             ui.write(_("    aliases: %s\n\n") % " ".join(d['aliases']))
 
 
 def allextensionnames():
     return extensions.enabled().keys() + extensions.disabled().keys()
 
 if __name__ == "__main__":
     doc = 'hg.1.gendoc'
     if len(sys.argv) > 1:
         doc = sys.argv[1]
 
     ui = uimod.ui.load()
     if doc == 'hg.1.gendoc':
         showdoc(ui)
     else:
         showtopic(ui, sys.argv[1])

mercurial/help.py

@@ -1,694 +1,736 b''
 # help.py - help data for mercurial
 #
 # Copyright 2006 Matt Mackall <[e-mail]>
 #
 # 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,
+    registrar,
     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)"),
 }
 
+# The order in which command categories will be displayed.
+# Extensions with custom categories should insert them into this list
+# after/before the appropriate item, rather than replacing the list or
+# assuming absolute positions.
+CATEGORY_ORDER = [
+    registrar.command.CATEGORY_NONE,
+]
+
+# Human-readable category names. These are translated.
+# Extensions with custom categories should add their names here.
+CATEGORY_NAMES = {
+    registrar.command.CATEGORY_NONE: 'Uncategorized commands',
+}
+
 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')),
     (['cbor'], _('CBOR'),
      loaddoc('cbor', 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')),
     (['wireprotocolrpc'], _('Wire Protocol RPC'),
      loaddoc('wireprotocolrpc', subdir='internals')),
     (['wireprotocolv2'], _('Wire Protocol Version 2'),
      loaddoc('wireprotocolv2', 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:
             # py3 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')
-
+        # Category -> list of commands
+        cats = {}
+        # Command -> short description
         h = {}
-        cmds = {}
+        # Command -> string showing synonyms
+        syns = {}
         for c, e in commands.table.iteritems():
             fs = cmdutil.parsealiases(c)
             f = fs[0]
+            syns[f] = ', '.join(fs)
+            func = e[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__):
+                func.__module__ != commands.__name__):
                 continue
             if name == "shortlist" and not p:
                 continue
-            doc = pycompat.getdoc(e[0])
+            doc = pycompat.getdoc(func)
             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)
+
+            cat = getattr(func, 'helpcategory', None) or (
+                registrar.command.CATEGORY_NONE)
+            cats.setdefault(cat, []).append(f)
 
         rst = []
         if not h:
             if not ui.quiet:
                 rst.append(_('no commands defined\n'))
             return rst
 
+        # Output top header.
         if not ui.quiet:
-            rst.append(header)
-        fns = sorted(h)
-        for f in fns:
+            if name == "shortlist":
+                rst.append(_('basic commands:\n\n'))
+            elif name == "debug":
+                rst.append(_('debug commands (internal and unsupported):\n\n'))
+            else:
+                rst.append(_('list of commands:\n'))
+
+        def appendcmds(cmds):
+            cmds = sorted(cmds)
+            for c in cmds:
             if ui.verbose:
-                commacmds = cmds[f].replace("|",", ")
-                rst.append(" :%s: %s\n" % (commacmds, h[f]))
+                    rst.append(" :%s: %s\n" % (syns[c], h[c]))
+                else:
+                    rst.append(' :%s: %s\n' % (c, h[c]))
+
+        if name in ('shortlist', 'debug'):
+            # List without categories.
+            appendcmds(h)
             else:
-                rst.append(' :%s: %s\n' % (f, h[f]))
+            # Check that all categories have an order.
+            missing_order = set(cats.keys()) - set(CATEGORY_ORDER)
+            if missing_order:
+                ui.develwarn('help categories missing from CATEGORY_ORDER: %s' %
+                             missing_order)
+
+            # List per category.
+            for cat in CATEGORY_ORDER:
+                catfns = cats.get(cat, [])
+                if catfns:
+                    if len(cats) > 1:
+                        catname = gettext(CATEGORY_NAMES[cat])
+                        rst.append("\n%s:\n" % catname)
+                    rst.append("\n")
+                    appendcmds(catfns)
 
         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():
+            elif name and syns and name in syns.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, fullname, 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>[.<subtopic][.<section>]
     name = subtopic = section = None
     if fullname is not None:
         nameparts = fullname.split('.')
         name = nameparts.pop(0)
         if nameparts and name in subtopics:
             subtopic = nameparts.pop(0)
         if nameparts:
             section = encoding.lower('.'.join(nameparts))
 
     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)
 
     blocks, pruned = minirst.parse(text, keep=keep)
     if 'verbose' in pruned:
         keep.append('omitted')
     else:
         keep.append('notomitted')
     blocks, pruned = minirst.parse(text, keep=keep)
     if section:
         blocks = minirst.filtersections(blocks, 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 (blocks and name):
         raise error.Abort(_("help section not found: %s") % fullname)
 
     return minirst.formatplain(blocks, textwidth)

mercurial/registrar.py

@@ -1,467 +1,474 b''
 # registrar.py - utilities to register function for specific purpose
 #
 #  Copyright FUJIWARA Katsunori <[e-mail]> and others
 #
 # 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
 
 from . import (
     configitems,
     error,
     pycompat,
     util,
 )
 
 # unlike the other registered items, config options are neither functions or
 # classes. Registering the option is just small function call.
 #
 # We still add the official API to the registrar module for consistency with
 # the other items extensions want might to register.
 configitem = configitems.getitemregister
 
 class _funcregistrarbase(object):
     """Base of decorator to register a function for specific purpose
 
     This decorator stores decorated functions into own dict 'table'.
 
     The least derived class can be defined by overriding 'formatdoc',
     for example::
 
         class keyword(_funcregistrarbase):
             _docformat = ":%s: %s"
 
     This should be used as below:
 
         keyword = registrar.keyword()
 
         @keyword('bar')
         def barfunc(*args, **kwargs):
             '''Explanation of bar keyword ....
             '''
             pass
 
     In this case:
 
     - 'barfunc' is stored as 'bar' in '_table' of an instance 'keyword' above
     - 'barfunc.__doc__' becomes ":bar: Explanation of bar keyword"
     """
     def __init__(self, table=None):
         if table is None:
             self._table = {}
         else:
             self._table = table
 
     def __call__(self, decl, *args, **kwargs):
         return lambda func: self._doregister(func, decl, *args, **kwargs)
 
     def _doregister(self, func, decl, *args, **kwargs):
         name = self._getname(decl)
 
         if name in self._table:
             msg = 'duplicate registration for name: "%s"' % name
             raise error.ProgrammingError(msg)
 
         if func.__doc__ and not util.safehasattr(func, '_origdoc'):
             doc = pycompat.sysbytes(func.__doc__).strip()
             func._origdoc = doc
             func.__doc__ = pycompat.sysstr(self._formatdoc(decl, doc))
 
         self._table[name] = func
         self._extrasetup(name, func, *args, **kwargs)
 
         return func
 
     def _parsefuncdecl(self, decl):
         """Parse function declaration and return the name of function in it
         """
         i = decl.find('(')
         if i >= 0:
             return decl[:i]
         else:
             return decl
 
     def _getname(self, decl):
         """Return the name of the registered function from decl
 
         Derived class should override this, if it allows more
         descriptive 'decl' string than just a name.
         """
         return decl
 
     _docformat = None
 
     def _formatdoc(self, decl, doc):
         """Return formatted document of the registered function for help
 
         'doc' is '__doc__.strip()' of the registered function.
         """
         return self._docformat % (decl, doc)
 
     def _extrasetup(self, name, func):
         """Execute exra setup for registered function, if needed
         """
 
 class command(_funcregistrarbase):
     """Decorator to register a command function to table
 
     This class receives a command table as its argument. The table should
     be a dict.
 
     The created object can be used as a decorator for adding commands to
     that command table. This accepts multiple arguments to define a command.
 
     The first argument is the command name (as bytes).
 
     The `options` keyword argument is an iterable of tuples defining command
     arguments. See ``mercurial.fancyopts.fancyopts()`` for the format of each
     tuple.
 
     The `synopsis` argument defines a short, one line summary of how to use the
     command. This shows up in the help output.
 
     There are three arguments that control what repository (if any) is found
     and passed to the decorated function: `norepo`, `optionalrepo`, and
     `inferrepo`.
 
     The `norepo` argument defines whether the command does not require a
     local repository. Most commands operate against a repository, thus the
     default is False. When True, no repository will be passed.
 
     The `optionalrepo` argument defines whether the command optionally requires
     a local repository. If no repository can be found, None will be passed
     to the decorated function.
 
     The `inferrepo` argument defines whether to try to find a repository from
     the command line arguments. If True, arguments will be examined for
     potential repository locations. See ``findrepo()``. If a repository is
     found, it will be used and passed to the decorated function.
 
     The `intents` argument defines a set of intended actions or capabilities
     the command is taking. These intents can be used to affect the construction
     of the repository object passed to the command. For example, commands
     declaring that they are read-only could receive a repository that doesn't
     have any methods allowing repository mutation. Other intents could be used
     to prevent the command from running if the requested intent could not be
     fulfilled.
 
+    If `helpcategory` is set (usually to one of the constants in the help
+    module), the command will be displayed under that category in the help's
+    list of commands.
+
     The following intents are defined:
 
     readonly
        The command is read-only
 
     The signature of the decorated function looks like this:
         def cmd(ui[, repo] [, <args>] [, <options>])
 
       `repo` is required if `norepo` is False.
       `<args>` are positional args (or `*args`) arguments, of non-option
       arguments from the command line.
       `<options>` are keyword arguments (or `**options`) of option arguments
       from the command line.
 
     See the WritingExtensions and MercurialApi documentation for more exhaustive
     descriptions and examples.
     """
 
+    # Command categories for grouping them in help output.
+    CATEGORY_NONE = 'none'
+
     def _doregister(self, func, name, options=(), synopsis=None,
                     norepo=False, optionalrepo=False, inferrepo=False,
-                    intents=None):
-
+                    intents=None, helpcategory=None):
         func.norepo = norepo
         func.optionalrepo = optionalrepo
         func.inferrepo = inferrepo
         func.intents = intents or set()
+        func.helpcategory = helpcategory
         if synopsis:
             self._table[name] = func, list(options), synopsis
         else:
             self._table[name] = func, list(options)
         return func
 
 INTENT_READONLY = b'readonly'
 
 class revsetpredicate(_funcregistrarbase):
     """Decorator to register revset predicate
 
     Usage::
 
         revsetpredicate = registrar.revsetpredicate()
 
         @revsetpredicate('mypredicate(arg1, arg2[, arg3])')
         def mypredicatefunc(repo, subset, x):
             '''Explanation of this revset predicate ....
             '''
             pass
 
     The first string argument is used also in online help.
 
     Optional argument 'safe' indicates whether a predicate is safe for
     DoS attack (False by default).
 
     Optional argument 'takeorder' indicates whether a predicate function
     takes ordering policy as the last argument.
 
     Optional argument 'weight' indicates the estimated run-time cost, useful
     for static optimization, default is 1. Higher weight means more expensive.
     Usually, revsets that are fast and return only one revision has a weight of
     0.5 (ex. a symbol); revsets with O(changelog) complexity and read only the
     changelog have weight 10 (ex. author); revsets reading manifest deltas have
     weight 30 (ex. adds); revset reading manifest contents have weight 100
     (ex. contains). Note: those values are flexible. If the revset has a
     same big-O time complexity as 'contains', but with a smaller constant, it
     might have a weight of 90.
 
     'revsetpredicate' instance in example above can be used to
     decorate multiple functions.
 
     Decorated functions are registered automatically at loading
     extension, if an instance named as 'revsetpredicate' is used for
     decorating in extension.
 
     Otherwise, explicit 'revset.loadpredicate()' is needed.
     """
     _getname = _funcregistrarbase._parsefuncdecl
     _docformat = "``%s``\n    %s"
 
     def _extrasetup(self, name, func, safe=False, takeorder=False, weight=1):
         func._safe = safe
         func._takeorder = takeorder
         func._weight = weight
 
 class filesetpredicate(_funcregistrarbase):
     """Decorator to register fileset predicate
 
     Usage::
 
         filesetpredicate = registrar.filesetpredicate()
 
         @filesetpredicate('mypredicate()')
         def mypredicatefunc(mctx, x):
             '''Explanation of this fileset predicate ....
             '''
             pass
 
     The first string argument is used also in online help.
 
     Optional argument 'callstatus' indicates whether a predicate
      implies 'matchctx.status()' at runtime or not (False, by
      default).
 
     Optional argument 'weight' indicates the estimated run-time cost, useful
     for static optimization, default is 1. Higher weight means more expensive.
     There are predefined weights in the 'filesetlang' module.
 
     ====== =============================================================
     Weight Description and examples
     ====== =============================================================
     0.5    basic match patterns (e.g. a symbol)
     10     computing status (e.g. added()) or accessing a few files
     30     reading file content for each (e.g. grep())
     50     scanning working directory (ignored())
     ====== =============================================================
 
     'filesetpredicate' instance in example above can be used to
     decorate multiple functions.
 
     Decorated functions are registered automatically at loading
     extension, if an instance named as 'filesetpredicate' is used for
     decorating in extension.
 
     Otherwise, explicit 'fileset.loadpredicate()' is needed.
     """
     _getname = _funcregistrarbase._parsefuncdecl
     _docformat = "``%s``\n    %s"
 
     def _extrasetup(self, name, func, callstatus=False, weight=1):
         func._callstatus = callstatus
         func._weight = weight
 
 class _templateregistrarbase(_funcregistrarbase):
     """Base of decorator to register functions as template specific one
     """
     _docformat = ":%s: %s"
 
 class templatekeyword(_templateregistrarbase):
     """Decorator to register template keyword
 
     Usage::
 
         templatekeyword = registrar.templatekeyword()
 
         # new API (since Mercurial 4.6)
         @templatekeyword('mykeyword', requires={'repo', 'ctx'})
         def mykeywordfunc(context, mapping):
             '''Explanation of this template keyword ....
             '''
             pass
 
         # old API (DEPRECATED)
         @templatekeyword('mykeyword')
         def mykeywordfunc(repo, ctx, templ, cache, revcache, **args):
             '''Explanation of this template keyword ....
             '''
             pass
 
     The first string argument is used also in online help.
 
     Optional argument 'requires' should be a collection of resource names
     which the template keyword depends on. This also serves as a flag to
     switch to the new API. If 'requires' is unspecified, all template
     keywords and resources are expanded to the function arguments.
 
     'templatekeyword' instance in example above can be used to
     decorate multiple functions.
 
     Decorated functions are registered automatically at loading
     extension, if an instance named as 'templatekeyword' is used for
     decorating in extension.
 
     Otherwise, explicit 'templatekw.loadkeyword()' is needed.
     """
 
     def _extrasetup(self, name, func, requires=None):
         func._requires = requires
 
 class templatefilter(_templateregistrarbase):
     """Decorator to register template filer
 
     Usage::
 
         templatefilter = registrar.templatefilter()
 
         @templatefilter('myfilter', intype=bytes)
         def myfilterfunc(text):
             '''Explanation of this template filter ....
             '''
             pass
 
     The first string argument is used also in online help.
 
     Optional argument 'intype' defines the type of the input argument,
     which should be (bytes, int, templateutil.date, or None for any.)
 
     'templatefilter' instance in example above can be used to
     decorate multiple functions.
 
     Decorated functions are registered automatically at loading
     extension, if an instance named as 'templatefilter' is used for
     decorating in extension.
 
     Otherwise, explicit 'templatefilters.loadkeyword()' is needed.
     """
 
     def _extrasetup(self, name, func, intype=None):
         func._intype = intype
 
 class templatefunc(_templateregistrarbase):
     """Decorator to register template function
 
     Usage::
 
         templatefunc = registrar.templatefunc()
 
         @templatefunc('myfunc(arg1, arg2[, arg3])', argspec='arg1 arg2 arg3',
                       requires={'ctx'})
         def myfuncfunc(context, mapping, args):
             '''Explanation of this template function ....
             '''
             pass
 
     The first string argument is used also in online help.
 
     If optional 'argspec' is defined, the function will receive 'args' as
     a dict of named arguments. Otherwise 'args' is a list of positional
     arguments.
 
     Optional argument 'requires' should be a collection of resource names
     which the template function depends on.
 
     'templatefunc' instance in example above can be used to
     decorate multiple functions.
 
     Decorated functions are registered automatically at loading
     extension, if an instance named as 'templatefunc' is used for
     decorating in extension.
 
     Otherwise, explicit 'templatefuncs.loadfunction()' is needed.
     """
     _getname = _funcregistrarbase._parsefuncdecl
 
     def _extrasetup(self, name, func, argspec=None, requires=()):
         func._argspec = argspec
         func._requires = requires
 
 class internalmerge(_funcregistrarbase):
     """Decorator to register in-process merge tool
 
     Usage::
 
         internalmerge = registrar.internalmerge()
 
         @internalmerge('mymerge', internalmerge.mergeonly,
                        onfailure=None, precheck=None,
                        binary=False, symlink=False):
         def mymergefunc(repo, mynode, orig, fcd, fco, fca,
                         toolconf, files, labels=None):
             '''Explanation of this internal merge tool ....
             '''
             return 1, False # means "conflicted", "no deletion needed"
 
     The first string argument is used to compose actual merge tool name,
     ":name" and "internal:name" (the latter is historical one).
 
     The second argument is one of merge types below:
 
     ========== ======== ======== =========
     merge type precheck premerge fullmerge
     ========== ======== ======== =========
     nomerge     x        x        x
     mergeonly   o        x        o
     fullmerge   o        o        o
     ========== ======== ======== =========
 
     Optional argument 'onfailure' is the format of warning message
     to be used at failure of merging (target filename is specified
     at formatting). Or, None or so, if warning message should be
     suppressed.
 
     Optional argument 'precheck' is the function to be used
     before actual invocation of internal merge tool itself.
     It takes as same arguments as internal merge tool does, other than
     'files' and 'labels'. If it returns false value, merging is aborted
     immediately (and file is marked as "unresolved").
 
     Optional argument 'binary' is a binary files capability of internal
     merge tool. 'nomerge' merge type implies binary=True.
 
     Optional argument 'symlink' is a symlinks capability of inetrnal
     merge function. 'nomerge' merge type implies symlink=True.
 
     'internalmerge' instance in example above can be used to
     decorate multiple functions.
 
     Decorated functions are registered automatically at loading
     extension, if an instance named as 'internalmerge' is used for
     decorating in extension.
 
     Otherwise, explicit 'filemerge.loadinternalmerge()' is needed.
     """
     _docformat = "``:%s``\n    %s"
 
     # merge type definitions:
     nomerge = None
     mergeonly = 'mergeonly'  # just the full merge, no premerge
     fullmerge = 'fullmerge'  # both premerge and merge
 
     def _extrasetup(self, name, func, mergetype,
                     onfailure=None, precheck=None,
                     binary=False, symlink=False):
         func.mergetype = mergetype
         func.onfailure = onfailure
         func.precheck = precheck
 
         binarycap = binary or mergetype == self.nomerge
         symlinkcap = symlink or mergetype == self.nomerge
 
         # actual capabilities, which this internal merge tool has
         func.capabilities = {"binary": binarycap, "symlink": symlinkcap}