Mercurial > public > mercurial-scm > hg-stable

annotate doc/gendoc.py @ 12756:13f0acfa974a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
gendoc: refactor get_cmd Refactors the get_cmd to take the table as argument, instad of just referencing the global table, thereby enabling reuse for extension command tables.
author Erik Zielke <ez@aragost.com>
date Mon, 18 Oct 2010 14:37:52 +0200
parents 2d88369a27bf
children 4f4eddee254d
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
9484
c96d73dd956d gendoc: do not wrap encoded string
Martin Geisler <mg@lazybytes.net>
parents: 9317
diff changeset
1 import os, sys
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
2 # import from the live mercurial repo
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
3 sys.path.insert(0, "..")
9130
335f749cc369 gendoc: fall back to pure modules if C extensions are not available (issue1711)
C?dric Duval <cedricduval@free.fr>
parents: 9021
diff changeset
4 # fall back to pure modules if required C extensions are not available
335f749cc369 gendoc: fall back to pure modules if C extensions are not available (issue1711)
C?dric Duval <cedricduval@free.fr>
parents: 9021
diff changeset
5 sys.path.append(os.path.join('..', 'mercurial', 'pure'))
5209
bbdcdc7f170e gendoc: use demandimport
Matt Mackall <mpm@selenic.com>
parents: 3797
diff changeset
6 from mercurial import demandimport; demandimport.enable()
9485
7d6ac5d7917c test-gendoc: add tests for all languages
Martin Geisler <mg@lazybytes.net>
parents: 9484
diff changeset
7 from mercurial import encoding
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
8 from mercurial.commands import table, globalopts
9240
b6cb3af61582 gendoc: don't translate topic strings twice (issue1760)
C?dric Duval <cedricduval@free.fr>
parents: 9130
diff changeset
9 from mercurial.i18n import _
3797
54fd4d3b4fce Generate docs for help topics
Matt Mackall <mpm@selenic.com>
parents: 1814
diff changeset
10 from mercurial.help import helptable
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
11
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
12 def get_desc(docstr):
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
13 if not docstr:
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
14 return "", ""
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
15 # sanitize
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
16 docstr = docstr.strip("\n")
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
17 docstr = docstr.rstrip()
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
18 shortdesc = docstr.splitlines()[0].strip()
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
19
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
20 i = docstr.find("\n")
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
21 if i != -1:
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 9792
diff changeset
22 desc = docstr[i + 2:]
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
23 else:
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
24 desc = " %s" % shortdesc
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
25 return (shortdesc, desc)
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
26
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
27 def get_opts(opts):
11321
40c06bbf58be help: show value requirement and multiple occurrence of options
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 10282
diff changeset
28 for opt in opts:
40c06bbf58be help: show value requirement and multiple occurrence of options
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 10282
diff changeset
29 if len(opt) == 5:
40c06bbf58be help: show value requirement and multiple occurrence of options
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 10282
diff changeset
30 shortopt, longopt, default, desc, optlabel = opt
40c06bbf58be help: show value requirement and multiple occurrence of options
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 10282
diff changeset
31 else:
40c06bbf58be help: show value requirement and multiple occurrence of options
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 10282
diff changeset
32 shortopt, longopt, default, desc = opt
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
33 allopts = []
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
34 if shortopt:
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
35 allopts.append("-%s" % shortopt)
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
36 if longopt:
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
37 allopts.append("--%s" % longopt)
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
38 desc += default and _(" (default: %s)") % default or ""
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
39 yield(", ".join(allopts), desc)
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
40
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
41 def get_cmd(cmd, cmdtable):
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
42 d = {}
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
43 attr = cmdtable[cmd]
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
44 cmds = cmd.lstrip("^").split("|")
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
45
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
46 d['cmd'] = cmds[0]
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
47 d['aliases'] = cmd.split("|")[1:]
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
48 d['desc'] = get_desc(attr[0].__doc__)
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
49 d['opts'] = list(get_opts(attr[1]))
7376
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
50
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
51 s = 'hg ' + cmds[0]
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
52 if len(attr) > 2:
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
53 if not attr[2].startswith('hg'):
8546
a33d19dcf906 gendoc: add missing space in command synopsis
Ori Avtalion <ori@avtalion.name>
parents: 7376
diff changeset
54 s += ' ' + attr[2]
7376
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
55 else:
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
56 s = attr[2]
9622
9d1a480ca6ea gendoc: fix synopsis
Martin Geisler <mg@lazybytes.net>
parents: 9485
diff changeset
57 d['synopsis'] = s.strip()
7376
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
58
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
59 return d
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
60
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
61 def show_doc(ui):
9296
5043a5b16d91 gendoc: rename underlined/bold to section/subsection
Martin Geisler <mg@lazybytes.net>
parents: 9241
diff changeset
62 def section(s):
9485
7d6ac5d7917c test-gendoc: add tests for all languages
Martin Geisler <mg@lazybytes.net>
parents: 9484
diff changeset
63 ui.write("%s\n%s\n\n" % (s, "-" * encoding.colwidth(s)))
9296
5043a5b16d91 gendoc: rename underlined/bold to section/subsection
Martin Geisler <mg@lazybytes.net>
parents: 9241
diff changeset
64 def subsection(s):
9485
7d6ac5d7917c test-gendoc: add tests for all languages
Martin Geisler <mg@lazybytes.net>
parents: 9484
diff changeset
65 ui.write("%s\n%s\n\n" % (s, '"' * encoding.colwidth(s)))
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
66
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
67 # print options
9792
dd1a95ccbe07 doc: use titlecase in man page section titles
Martin Geisler <mg@lazybytes.net>
parents: 9622
diff changeset
68 section(_("Options"))
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
69 for optstr, desc in get_opts(globalopts):
9158
d6eecafaf12f doc: use reStructuredText for man and HTML pages
Martin Geisler <mg@lazybytes.net>
parents: 9130
diff changeset
70 ui.write("%s\n %s\n\n" % (optstr, desc))
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
71
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
72 # print cmds
9792
dd1a95ccbe07 doc: use titlecase in man page section titles
Martin Geisler <mg@lazybytes.net>
parents: 9622
diff changeset
73 section(_("Commands"))
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
74 commandprinter(ui, table)
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
75
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
76 # print topics
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
77 for names, sec, doc in helptable:
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
78 for name in names:
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
79 ui.write(".. _%s:\n" % name)
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
80 ui.write("\n")
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
81 section(sec)
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
82 if hasattr(doc, '__call__'):
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
83 doc = doc()
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
84 ui.write(doc)
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
85 ui.write("\n")
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
86
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
87 def commandprinter(ui, cmdtable):
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
88 h = {}
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
89 for c, attr in cmdtable.items():
6488
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
90 f = c.split("|")[0]
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
91 f = f.lstrip("^")
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
92 h[f] = c
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
93 cmds = h.keys()
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
94 cmds.sort()
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
95
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
96 for f in cmds:
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 9792
diff changeset
97 if f.startswith("debug"):
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 9792
diff changeset
98 continue
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
99 d = get_cmd(h[f], cmdtable)
6488
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
100 # synopsis
9158
d6eecafaf12f doc: use reStructuredText for man and HTML pages
Martin Geisler <mg@lazybytes.net>
parents: 9130
diff changeset
101 ui.write(".. _%s:\n\n" % d['cmd'])
d6eecafaf12f doc: use reStructuredText for man and HTML pages
Martin Geisler <mg@lazybytes.net>
parents: 9130
diff changeset
102 ui.write("``%s``\n" % d['synopsis'].replace("hg ","", 1))
6488
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
103 # description
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
104 ui.write("%s\n\n" % d['desc'][1])
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
105 # options
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
106 opt_output = list(d['opts'])
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
107 if opt_output:
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
108 opts_len = max([len(line[0]) for line in opt_output])
9158
d6eecafaf12f doc: use reStructuredText for man and HTML pages
Martin Geisler <mg@lazybytes.net>
parents: 9130
diff changeset
109 ui.write(_(" options:\n\n"))
6488
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
110 for optstr, desc in opt_output:
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
111 if desc:
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
112 s = "%-*s %s" % (opts_len, optstr, desc)
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
113 else:
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
114 s = optstr
9484
c96d73dd956d gendoc: do not wrap encoded string
Martin Geisler <mg@lazybytes.net>
parents: 9317
diff changeset
115 ui.write(" %s\n" % s)
6488
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
116 ui.write("\n")
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
117 # aliases
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
118 if d['aliases']:
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
119 ui.write(_(" aliases: %s\n\n") % " ".join(d['aliases']))
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
120
3797
54fd4d3b4fce Generate docs for help topics
Matt Mackall <mpm@selenic.com>
parents: 1814
diff changeset
121
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
122 if __name__ == "__main__":
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
123 show_doc(sys.stdout)