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

Martin Geisler mg at aragost.com
Tue Oct 19 02:48:35 CDT 2010


Erik Zielke <ez at aragost.com> writes:

> # HG changeset patch
> # User Erik Zielke <ez at aragost.com>
> # Date 1287406401 -7200
> # Node ID 9cbe3419825fdc15e83c83073cbcdb2713b800ef
> # Parent  bc4f8b25cbbf1de33ba54dec5e662411086e9489
> gendoc: automatically create help for default extensions.
>
> Creates help for extensions by extracting doc strings from the
> extension module and its commands.

For those not in the know (i.e., those not sitting at a desk besides
Erik) this patch adds a section called "Extensions" to the hg.1 manpage
(and therefore also to the corresponding hg.1.html file) which lists the
extensions. Each extension is listed with its module docstring, followed
by the commands defined by that extension -- just like we do it for the
core commands.

(The commit message could be expanded with some of the above.)

Erik and I debated a bit if this would make better sense as a hgext.1
manpage and we also discussed how this fits with the new hgweb help
system. My take is that generating a manpage for the extensions is a
nice low-hanging fruit and so we should just do it and then worry about
the overlap with the hgweb help later (the hgweb help obviously already
overlaps with the current hg.1.html file).

> diff -r bc4f8b25cbbf -r 9cbe3419825f doc/gendoc.py
> --- a/doc/gendoc.py	Mon Oct 18 14:52:29 2010 +0200
> +++ b/doc/gendoc.py	Mon Oct 18 14:53:21 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

> +
> +    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', None), subsubsubsection)

If hasattr(mod, 'cmdtable'), then there is no reason to give a default
of None to getattr. I would suggest

  cmdtable = getattr(mod, 'cmdtable', None)
  if cmdtable:
     ... use cmdtable

> +def commandprinter(ui, cmdtable, cmdlevel):

I would probably rename 'cmdlevel' to 'sectionfunc' or something like
that -- 'func' is a common suffix used on variables that are callable.

>      h = {}
>      for c, attr in cmdtable.items():
>          f = c.split("|")[0]
> @@ -101,9 +124,13 @@
>              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")
> +        cmdlevel(d['cmd'])
> +
> +        synopsislines = d['synopsis'].splitlines()
> +        ui.write("::\n\n")
> +        for line in synopsislines:

This surprised me when you first told me about it... so I suggest adding
a comment for future generations:

               # some commands (such as rebase) has a multi-line synopsis

> +            ui.write("   %s\n" % line.replace("hg ","", 1))
> +        ui.write('\n')
>          # description
>          ui.write("%s\n\n" % d['desc'][1])
>          # options
> @@ -123,5 +150,18 @@
>              ui.write(_("    aliases: %s\n\n") % " ".join(d['aliases']))
>  
>  
> +def allextensionnames():
> +    extensionnames = []
> +
> +    def getnames(dictandlen):
> +        dict, len = dictandlen
> +        extensionnames.extend(dict.keys())
> +
> +    getnames(extensions.enabled())
> +    getnames(extensions.disabled())
> +
> +    return extensionnames

The inner function seems like overkill here.

>  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; }
> @@ -299,3 +301,4 @@
>  ul.auto-toc {
>      list-style-type: none;
>  }
> +

Spurious change.

-- 
Martin Geisler

aragost Trifork
Professional Mercurial support
http://aragost.com/mercurial/


More information about the Mercurial-devel mailing list