Patchwork [4,of,4,STABLE] doc: show details of command options in pages generated by docutils

login
register
mail settings
Submitter Katsunori FUJIWARA
Date Oct. 24, 2013, 4:22 p.m.
Message ID <77fbd06f87a88c86bca7.1382631759@juju>
Download mbox | patch
Permalink /patch/2818/
State Superseded
Headers show

Comments

Katsunori FUJIWARA - Oct. 24, 2013, 4:22 p.m.
# HG changeset patch
# User FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
# Date 1382631258 -32400
#      Fri Oct 25 01:14:18 2013 +0900
# Branch stable
# Node ID 77fbd06f87a88c86bca7ab1d5f40713060e360ed
# Parent  1837deb4f44886b30f1443fbd07879de2908e7dc
doc: show details of command options in pages generated by docutils

Before this patch, HTML/man pages generated by docutils don't show
details of each command options, whether it should take argument or
not for example, even though "hg help" does.

This patch shows details of command options as same as "hg help"
shows.

This patch uses "--option <VALUE[+]>" style instead of "--option
<VALUE> [+]" used in output of "hg help", because docutils requires
that option argument strings starts with "<" and ends with ">".
Matt Mackall - Oct. 25, 2013, 8:23 p.m.
On Fri, 2013-10-25 at 01:22 +0900, FUJIWARA Katsunori wrote:
> # HG changeset patch
> # User FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
> # Date 1382631258 -32400
> #      Fri Oct 25 01:14:18 2013 +0900
> # Branch stable
> # Node ID 77fbd06f87a88c86bca7ab1d5f40713060e360ed
> # Parent  1837deb4f44886b30f1443fbd07879de2908e7dc
> doc: show details of command options in pages generated by docutils

I've queued the first three, thanks. This one looks fine, but resend it
in November, please.

Patch

diff --git a/doc/gendoc.py b/doc/gendoc.py
--- a/doc/gendoc.py
+++ b/doc/gendoc.py
@@ -40,11 +40,16 @@ 
             shortopt, longopt, default, desc, optlabel = opt
         else:
             shortopt, longopt, default, desc = opt
+            optlabel = _("VALUE")
         allopts = []
         if shortopt:
             allopts.append("-%s" % shortopt)
         if longopt:
             allopts.append("--%s" % longopt)
+        if isinstance(default, list):
+            allopts[-1] += " <%s[+]>" % optlabel
+        elif (default is not None) and not isinstance(default, bool):
+            allopts[-1] += " <%s>" % optlabel
         desc += default and _(" (default: %s)") % default or ""
         yield (", ".join(allopts), desc)
 
@@ -71,8 +76,14 @@ 
 def showdoc(ui):
     # print options
     ui.write(minirst.section(_("Options")))
+    multioccur = False
     for optstr, desc in get_opts(globalopts):
         ui.write("%s\n    %s\n\n" % (optstr, desc))
+        if optstr.endswith("[+]>"):
+            multioccur = True
+    if multioccur:
+        ui.write(_("\n[+] marked option can be specified multiple times\n"))
+        ui.write("\n")
 
     # print cmds
     ui.write(minirst.section(_("Commands")))
@@ -157,12 +168,18 @@ 
         if opt_output:
             opts_len = max([len(line[0]) for line in opt_output])
             ui.write(_("Options:\n\n"))
+            multioccur = False
             for optstr, desc in opt_output:
                 if desc:
                     s = "%-*s  %s" % (opts_len, optstr, desc)
                 else:
                     s = optstr
                 ui.write("%s\n" % s)
+                if optstr.endswith("[+]>"):
+                    multioccur = True
+            if multioccur:
+                ui.write(_("\n[+] marked option can be specified"
+                           " multiple times\n"))
             ui.write("\n")
         # aliases
         if d['aliases']: