Patchwork D6329: gendoc: nest command headers under category headers

login
register
mail settings
Submitter phabricator
Date May 5, 2019, 5:12 a.m.
Message ID <435f2d02a8b242ac51434457c69cbf30@localhost.localdomain>
Download mbox | patch
Permalink /patch/39957/
State Not Applicable
Headers show

Comments

phabricator - May 5, 2019, 5:12 a.m.
This revision was automatically updated to reflect the committed changes.
Closed by commit rHGa42cc325b682: gendoc: nest command headers under category headers (authored by Sietse, committed by ).

REPOSITORY
  rHG Mercurial

CHANGES SINCE LAST UPDATE
  https://phab.mercurial-scm.org/D6329?vs=15000&id=15015

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

AFFECTED FILES
  doc/gendoc.py

CHANGE DETAILS




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

Patch

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]
@@ -221,7 +242,7 @@ 
             if f.startswith(b"debug"):
                 continue
             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