help: splitting the topics by category

help: splitting the topics by category

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

--- a/doc/check-seclevel.py	Sat Oct 13 05:03:50 2018 -0700
+++ b/doc/check-seclevel.py	Fri Oct 12 17:57:36 2018 +0200
@@ -87,7 +87,8 @@
 
 def checkhghelps(ui):
     errorcnt = 0
-    for names, sec, doc in helptable:
+    for h in helptable:
+        names, sec, doc = h[0:3]
         if callable(doc):
             doc = doc(ui)
         errorcnt += checkseclevel(ui, doc,

--- a/mercurial/help.py	Sat Oct 13 05:03:50 2018 -0700
+++ b/mercurial/help.py	Fri Oct 12 17:57:36 2018 +0200
@@ -62,6 +62,22 @@
     registrar.command.CATEGORY_NONE: 'Uncategorized commands',
 }
 
+# Topic categories.
+TOPIC_CATEGORY_NONE = 'none'
+
+# The order in which topic 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.
+TOPIC_CATEGORY_ORDER = [
+    TOPIC_CATEGORY_NONE,
+]
+
+# Human-readable topic category names. These are translated.
+TOPIC_CATEGORY_NAMES = {
+    TOPIC_CATEGORY_NONE: 'Uncategorized topics',
+}
+
 def listexts(header, exts, indent=1, showdeprecated=False):
     '''return a text listing of the given extensions'''
     rst = []
@@ -152,7 +168,8 @@
                'extensions': [],
                'extensioncommands': [],
                }
-    for names, header, doc in helptable:
+    for topic in helptable:
+        names, header, doc = topic[0:3]
         # Old extensions may use a str as doc.
         if (sum(map(lowercontains, names))
             or lowercontains(header)
@@ -519,12 +536,35 @@
                 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))
+            rst.append(_("\nadditional help topics:\n"))
+            # Group commands by category.
+            topiccats = {}
+            for topic in helptable:
+                names, header, doc = topic[0:3]
+                if len(topic) > 3 and topic[3]:
+                    category = topic[3]
+                else:
+                    category = TOPIC_CATEGORY_NONE
+
+                topiccats.setdefault(category, []).append((names[0], header))
+
+            # Check that all categories have an order.
+            missing_order = set(topiccats.keys()) - set(TOPIC_CATEGORY_ORDER)
+            if missing_order:
+                ui.develwarn(
+                    'help categories missing from TOPIC_CATEGORY_ORDER: %s' %
+                    missing_order)
+
+            # Output topics per category.
+            for cat in TOPIC_CATEGORY_ORDER:
+                topics = topiccats.get(cat, [])
+                if topics:
+                    if len(topiccats) > 1:
+                        catname = gettext(TOPIC_CATEGORY_NAMES[cat])
+                        rst.append("\n%s:\n" % catname)
+                    rst.append("\n")
+                    for t, desc in topics:
+                        rst.append(" :%s: %s\n" % (t, desc))
 
         if ui.quiet:
             pass
@@ -559,7 +599,8 @@
                     break
 
         if not header:
-            for names, header, doc in helptable:
+            for topic in helptable:
+                names, header, doc = topic[0:3]
                 if name in names:
                     break
             else:

--- a/mercurial/hgweb/webcommands.py	Sat Oct 13 05:03:50 2018 -0700
+++ b/mercurial/hgweb/webcommands.py	Fri Oct 12 17:57:36 2018 +0200
@@ -1407,7 +1407,8 @@
     topicname = web.req.qsparams.get('node')
     if not topicname:
         def topics(context):
-            for entries, summary, _doc in helpmod.helptable:
+            for h in helpmod.helptable:
+                entries, summary, _doc = h[0:3]
                 yield {'topic': entries[0], 'summary': summary}
 
         early, other = [], []