D6329: gendoc: nest command headers under category headers

Sietse (Sietse Brouwer) phabricator at mercurial-scm.org
Sun Apr 28 17:17:43 EDT 2019


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

REPOSITORY
  rHG Mercurial

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

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
@@ -120,7 +120,7 @@
 
     # print cmds
     ui.write(minirst.section(_(b"Commands")))
-    commandprinter(ui, table, minirst.subsection)
+    commandprinter(ui, table, minirst.subsection, minirst.subsubsection)
 
     # print help topics
     # The config help topic is included in the hgrc.5 man page.
@@ -143,7 +143,8 @@
         cmdtable = getattr(mod, 'cmdtable', None)
         if cmdtable:
             ui.write(minirst.subsubsection(_(b'Commands')))
-            commandprinter(ui, cmdtable, minirst.subsubsubsection)
+            commandprinter(ui, cmdtable, minirst.subsubsubsection,
+                    minirst.subsubsubsubsection)
 
 def showtopic(ui, topic):
     extrahelptable = [
@@ -177,7 +178,27 @@
         ui.write(doc)
         ui.write(b"\n")
 
-def commandprinter(ui, cmdtable, sectionfunc):
+def commandprinter(ui, cmdtable, sectionfunc, subsectionfunc):
+    """Render restructuredtext describing a list of commands and their
+    documentations, grouped by command category.
+
+    Args:
+      ui: UI object to write the output to
+      cmdtable: a dict that maps a string of the command name plus its aliases
+        (separated with pipes) to a 3-tuple of (the command's function, a list
+        of its option descriptions, and a string summarizing available
+        options). Example, with aliases added for demonstration purposes:
+
+          'phase|alias1|alias2': (
+             <function phase at 0x7f0816b05e60>,
+             [ ('p', 'public', False, 'set changeset phase to public'),
+               ...,
+               ('r', 'rev', [], 'target revision', 'REV')],
+             '[-p|-d|-s] [-f] [-r] [REV...]'
+          )
+      sectionfunc: minirst function to format command category headers
+      subsectionfunc: minirst function to format command headers
+    """
     h = {}
     for c, attr in cmdtable.items():
         f = c.split(b"|")[0]
@@ -213,18 +234,16 @@
         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.
+        # Print a section header for the category. Skip empty categories.
         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
             processedcmds.append(f)  # log command
             d = get_cmd(h[f], cmdtable)
-            ui.write(sectionfunc(d[b'cmd']))
+            ui.write(subsectionfunc(d[b'cmd']))
             # short description
             ui.write(d[b'desc'][0])
             # synopsis



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


More information about the Mercurial-devel mailing list