[PATCH 4 of 4 v2] gendoc: automatically create help for default extensions

[Erik Zielke]

# HG changeset patch
# User Erik Zielke <ez at aragost.com>
# Date 1287489003 -7200
# Node ID 4952cbfebf8d090583ba4111417a8fb7ae274818
# Parent  2006cff2cdf323e3edab2f329ada4143e0cfef61
gendoc: automatically create help for default extensions.

Adds a section in the hg.1 manpage and corresponding hg.1.html
file. Each extension is listed with its module docstring, followed by
the commands defined by that extendsion.

Creates help for extensions by extracting doc strings from the extension modules
and its commands.

diff -r 2006cff2cdf3 -r 4952cbfebf8d doc/gendoc.py
--- a/doc/gendoc.py	Tue Oct 19 13:50:03 2010 +0200
+++ b/doc/gendoc.py	Tue Oct 19 13:50:03 2010 +0200
@@ -8,6 +8,7 @@
 from mercurial.commands import table, globalopts
 from mercurial.i18n import _
 from mercurial.help import helptable
+from mercurial import extensions
 
 def get_desc(docstr):
     if not docstr:
@@ -66,6 +67,10 @@
         ui.write("%s\n%s\n\n" % (s, "-" * encoding.colwidth(s)))
     def subsection(s):
         ui.write("%s\n%s\n\n" % (s, '"' * encoding.colwidth(s)))
+    def subsubsection(s):
+        ui.write("%s\n%s\n\n" % (s, "." * encoding.colwidth(s)))
+    def subsubsubsection(s):
+        ui.write("%s\n%s\n\n" % (s, "#" * encoding.colwidth(s)))
 
     # print options
     section(_("Options"))
@@ -74,7 +79,7 @@
 
     # print cmds
     section(_("Commands"))
-    commandprinter(ui, table)
+    commandprinter(ui, table, subsection)
 
     # print topics
     for names, sec, doc in helptable:
@@ -87,7 +92,25 @@
         ui.write(doc)
         ui.write("\n")
 
-def commandprinter(ui, cmdtable):
+    section(_("Extensions"))
+    ui.write("""
+
+.. contents::
+   :local:
+   :depth: 1
+
+""")
+
+    for extensionname in sorted(allextensionnames()):
+        mod = extensions.load(None, extensionname, None)
+        subsection(extensionname)
+        ui.write("%s\n\n" % mod.__doc__)
+        if hasattr(mod, 'cmdtable'):
+            subsubsection(_('Commands'))
+            commandprinter(ui, getattr(mod, 'cmdtable'), subsubsubsection)
+
+
+def commandprinter(ui, cmdtable, sectionfunc):
     h = {}
     for c, attr in cmdtable.items():
         f = c.split("|")[0]
@@ -101,9 +124,14 @@
             continue
         d = get_cmd(h[f], cmdtable)
         # synopsis
-        ui.write(".. _%s:\n\n" % d['cmd'])
-        ui.write("``%s``\n" % d['synopsis'].replace("hg ","", 1))
-        ui.write("\n")
+        sectionfunc(d['cmd'])
+
+        # some commands (such as rebase) have multi-line synopses
+        synopsislines = d['synopsis'].splitlines()
+        ui.write("::\n\n")
+        for line in synopsislines:
+            ui.write("   %s\n" % line.replace("hg ","", 1))
+        ui.write('\n')
         # description
         ui.write("%s\n\n" % d['desc'][1])
         # options
@@ -123,5 +151,17 @@
             ui.write(_("    aliases: %s\n\n") % " ".join(d['aliases']))
 
 
+def allextensionnames():
+    extensionnames = []
+
+    extensionsdictionary = extensions.enabled()[0]
+    extensionnames.extend(extensionsdictionary.keys())
+
+    extensionsdictionary = extensions.disabled()[0]
+    extensionnames.extend(extensionsdictionary.keys())
+
+    return extensionnames
+
+
 if __name__ == "__main__":
     show_doc(sys.stdout)
diff -r 2006cff2cdf3 -r 4952cbfebf8d doc/hg.1.txt
--- a/doc/hg.1.txt	Tue Oct 19 13:50:03 2010 +0200
+++ b/doc/hg.1.txt	Tue Oct 19 13:50:03 2010 +0200
@@ -14,7 +14,7 @@
 .. contents::
    :backlinks: top
    :class: htmlonly
-
+   :depth: 1
 
 Synopsis
 --------
diff -r 2006cff2cdf3 -r 4952cbfebf8d doc/style.css
--- a/doc/style.css	Tue Oct 19 13:50:03 2010 +0200
+++ b/doc/style.css	Tue Oct 19 13:50:03 2010 +0200
@@ -35,16 +35,18 @@
 table.docinfo { max-width: 72%; }
 
 /* headings */
-h1, h2, .topic-title, .admonition-title {
+h1, h2, h3, h4, .topic-title, .admonition-title {
     font-family: "MgOpen Cosmetica", "Lucida Sans Unicode", sans-serif;
     font-weight: normal;
 }
-h1, h2, .topic-title, .admonition-title {
+h1, h2, h3, h4, .topic-title, .admonition-title {
     margin: 1em 0 0.5em;
 }
 h1.title { font-size: 300%; }
 h2.subtitle, h1 { font-size: 200%; }
 h2, .topic-title, .admonition-title { font-size: 140%; }
+h3 { font-size: 125%; }
+h4 { font-size: 115%; }
 
 /* subtitle starts with lowercase in man pages, but not in HTML */
 h2.subtitle:first-letter { text-transform: uppercase; }