D6326: gendoc: group commands by category in man page and HTML help

[Sietse (Sietse Brouwer)]

Sietse created this revision.
Herald added a subscriber: mercurial-devel.
Herald added a reviewer: hg-reviewers.

REVISION SUMMARY
  Make Mercurial's man page and HTML help group commands by category, and
  present the categories in a helpful order. `hg help` already does this;
  this patch uses the same metadata.
  
  This patch uses the same header level for command categories, and for
  commands. A subsequent patch will push the command headers down one
  level.

REPOSITORY
  rHG Mercurial

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

AFFECTED FILES
  doc/gendoc.py

CHANGE DETAILS

diff --git a/doc/gendoc.py b/doc/gendoc.py
--- a/doc/gendoc.py
+++ b/doc/gendoc.py
@@ -185,8 +185,35 @@
         h[f] = c
     cmds = h.keys()
 
-    if True:
-        for f in sorted(cmds):
+    def helpcategory(cmd, h=h, cmdtable=cmdtable):
+        """Given a canonical command name from `cmds` (above), retrieve its
+        help category. If helpcategory is None, default to CATEGORY_NONE
+        """
+        fullname = h[cmd]
+        details = cmdtable[fullname]
+        helpcategory = details[0].helpcategory
+        if helpcategory is None:
+            return help.registrar.command.CATEGORY_NONE
+        return helpcategory
+
+    # Print the help for each command. We present the commands grouped by
+    # category, and we use help.CATEGORY_ORDER as a guide for a helpful order
+    # in which to present the categories.
+    for category in help.CATEGORY_ORDER:
+        # Make a list of the commands in this category.
+        # Rescanning the list of all commands for each category is quadratic;
+        # this is justified because N is low, and repeating the lookup keeps
+        # our data structure simpler.
+        categorycmds = sorted([
+            cmd for cmd in cmds
+            if helpcategory(cmd) == category])
+        # Print a section header for the category. Skip empty categories. For
+        # now, the category header is at the same level as the headers for the
+        # commands in the category; this is fixed in the next commit.
+        if categorycmds:
+            ui.write(sectionfunc(help.CATEGORY_NAMES[category]))
+        # Print each command in the category
+        for f in sorted(categorycmds):
             if f.startswith(b"debug"):
                 continue
             d = get_cmd(h[f], cmdtable)



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