D5066: help: splitting the topics by category

[rdamazio (Rodrigo Damazio Bovendorp)]

rdamazio updated this revision to Diff 12061.

REPOSITORY
  rHG Mercurial

CHANGES SINCE LAST UPDATE
  https://phab.mercurial-scm.org/D5066?vs=12040&id=12061

REVISION DETAIL
  https://phab.mercurial-scm.org/D5066

AFFECTED FILES
  mercurial/help.py
  mercurial/hgweb/webcommands.py

CHANGE DETAILS

diff --git a/mercurial/hgweb/webcommands.py b/mercurial/hgweb/webcommands.py
--- a/mercurial/hgweb/webcommands.py
+++ b/mercurial/hgweb/webcommands.py
@@ -1401,7 +1401,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 = [], []
diff --git a/mercurial/help.py b/mercurial/help.py
--- a/mercurial/help.py
+++ b/mercurial/help.py
@@ -58,6 +58,17 @@
     CATEGORY_NONE,
 ]
 
+# Topic categories.
+TOPIC_CATEGORY_NONE = _('Uncategorized topics')
+
+# 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,
+]
+
 def listexts(header, exts, indent=1, showdeprecated=False):
     '''return a text listing of the given extensions'''
     rst = []
@@ -148,7 +159,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)
@@ -514,12 +526,34 @@
                 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:
+                        rst.append("\n%s:\n" % cat)
+                    rst.append("\n")
+                    for t, desc in topics:
+                        rst.append(" :%s: %s\n" % (t, desc))
 
         if ui.quiet:
             pass
@@ -554,7 +588,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:



To: rdamazio, #hg-reviewers
Cc: mercurial-devel