Mercurial > public > mercurial-scm > hg

annotate doc/gendoc.py @ 12780:bdc1cf692447

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
gendoc: dedent documentation from docstrings When getting docstrings from the source they are indented to look good in the code. This indentation interferes with how the text is parsed by rst. Therefore this indentation is removed.
author Erik Zielke <ez@aragost.com>
date Tue, 19 Oct 2010 13:50:03 +0200
parents a19db59e1de4
children 0d09991f91ee
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
12780
bdc1cf692447 gendoc: dedent documentation from docstrings
Erik Zielke <ez@aragost.com>
parents: 12777
diff changeset
1 import os, sys, textwrap
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:
12780
bdc1cf692447 gendoc: dedent documentation from docstrings
Erik Zielke <ez@aragost.com>
parents: 12777
diff changeset
24 desc = shortdesc
bdc1cf692447 gendoc: dedent documentation from docstrings
Erik Zielke <ez@aragost.com>
parents: 12777
diff changeset
25
bdc1cf692447 gendoc: dedent documentation from docstrings
Erik Zielke <ez@aragost.com>
parents: 12777
diff changeset
26 desc = textwrap.dedent(desc)
bdc1cf692447 gendoc: dedent documentation from docstrings
Erik Zielke <ez@aragost.com>
parents: 12777
diff changeset
27
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
28 return (shortdesc, desc)
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
29
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
30 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
31 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
32 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
33 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
34 else:
40c06bbf58be help: show value requirement and multiple occurrence of options
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 10282
diff changeset
35 shortopt, longopt, default, desc = opt
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
36 allopts = []
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
37 if shortopt:
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
38 allopts.append("-%s" % shortopt)
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
39 if longopt:
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
40 allopts.append("--%s" % longopt)
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
41 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
42 yield(", ".join(allopts), desc)
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
43
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
44 def get_cmd(cmd, cmdtable):
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
45 d = {}
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
46 attr = cmdtable[cmd]
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
47 cmds = cmd.lstrip("^").split("|")
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
48
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
49 d['cmd'] = cmds[0]
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
50 d['aliases'] = cmd.split("|")[1:]
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
51 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
52 d['opts'] = list(get_opts(attr[1]))
7376
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
53
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
54 s = 'hg ' + cmds[0]
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
55 if len(attr) > 2:
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
56 if not attr[2].startswith('hg'):
8546
a33d19dcf906 gendoc: add missing space in command synopsis
Ori Avtalion <ori@avtalion.name>
parents: 7376
diff changeset
57 s += ' ' + attr[2]
7376
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
58 else:
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
59 s = attr[2]
9622
9d1a480ca6ea gendoc: fix synopsis
Martin Geisler <mg@lazybytes.net>
parents: 9485
diff changeset
60 d['synopsis'] = s.strip()
7376
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
61
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
62 return d
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
63
12776
4f4eddee254d gendoc: move section commands to module scope
Martin Geisler <mg@lazybytes.net>
parents: 12756
diff changeset
64 def section(ui, s):
4f4eddee254d gendoc: move section commands to module scope
Martin Geisler <mg@lazybytes.net>
parents: 12756
diff changeset
65 ui.write("%s\n%s\n\n" % (s, "-" * encoding.colwidth(s)))
4f4eddee254d gendoc: move section commands to module scope
Martin Geisler <mg@lazybytes.net>
parents: 12756
diff changeset
66
4f4eddee254d gendoc: move section commands to module scope
Martin Geisler <mg@lazybytes.net>
parents: 12756
diff changeset
67 def subsection(ui, s):
4f4eddee254d gendoc: move section commands to module scope
Martin Geisler <mg@lazybytes.net>
parents: 12756
diff changeset
68 ui.write("%s\n%s\n\n" % (s, '"' * encoding.colwidth(s)))
4f4eddee254d gendoc: move section commands to module scope
Martin Geisler <mg@lazybytes.net>
parents: 12756
diff changeset
69
4f4eddee254d gendoc: move section commands to module scope
Martin Geisler <mg@lazybytes.net>
parents: 12756
diff changeset
70
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
71 def show_doc(ui):
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
72 # print options
12776
4f4eddee254d gendoc: move section commands to module scope
Martin Geisler <mg@lazybytes.net>
parents: 12756
diff changeset
73 section(ui, _("Options"))
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
74 for optstr, desc in get_opts(globalopts):
12780
bdc1cf692447 gendoc: dedent documentation from docstrings
Erik Zielke <ez@aragost.com>
parents: 12777
diff changeset
75 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
76
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
77 # print cmds
12776
4f4eddee254d gendoc: move section commands to module scope
Martin Geisler <mg@lazybytes.net>
parents: 12756
diff changeset
78 section(ui, _("Commands"))
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
79 commandprinter(ui, table)
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
80
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
81 # print topics
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
82 for names, sec, doc in helptable:
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
83 for name in names:
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
84 ui.write(".. _%s:\n" % name)
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
85 ui.write("\n")
12776
4f4eddee254d gendoc: move section commands to module scope
Martin Geisler <mg@lazybytes.net>
parents: 12756
diff changeset
86 section(ui, sec)
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
87 if hasattr(doc, '__call__'):
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
88 doc = doc()
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
89 ui.write(doc)
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
90 ui.write("\n")
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
91
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
92 def commandprinter(ui, cmdtable):
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
93 h = {}
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
94 for c, attr in cmdtable.items():
6488
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
95 f = c.split("|")[0]
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
96 f = f.lstrip("^")
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
97 h[f] = c
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
98 cmds = h.keys()
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
99 cmds.sort()
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
100
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
101 for f in cmds:
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 9792
diff changeset
102 if f.startswith("debug"):
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 9792
diff changeset
103 continue
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
104 d = get_cmd(h[f], cmdtable)
12777
a19db59e1de4 gendoc: add subsection for each command
Martin Geisler <mg@lazybytes.net>
parents: 12776
diff changeset
105 subsection(ui, d['cmd'])
6488
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
106 # synopsis
9158
d6eecafaf12f doc: use reStructuredText for man and HTML pages
Martin Geisler <mg@lazybytes.net>
parents: 9130
diff changeset
107 ui.write("``%s``\n" % d['synopsis'].replace("hg ","", 1))
12780
bdc1cf692447 gendoc: dedent documentation from docstrings
Erik Zielke <ez@aragost.com>
parents: 12777
diff changeset
108 ui.write("\n")
6488
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
109 # description
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
110 ui.write("%s\n\n" % d['desc'][1])
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
111 # options
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
112 opt_output = list(d['opts'])
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
113 if opt_output:
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
114 opts_len = max([len(line[0]) for line in opt_output])
12780
bdc1cf692447 gendoc: dedent documentation from docstrings
Erik Zielke <ez@aragost.com>
parents: 12777
diff changeset
115 ui.write(_("options:\n\n"))
6488
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
116 for optstr, desc in opt_output:
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
117 if desc:
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
118 s = "%-*s %s" % (opts_len, optstr, desc)
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
119 else:
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
120 s = optstr
12780
bdc1cf692447 gendoc: dedent documentation from docstrings
Erik Zielke <ez@aragost.com>
parents: 12777
diff changeset
121 ui.write("%s\n" % s)
6488
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
122 ui.write("\n")
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
123 # aliases
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
124 if d['aliases']:
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
125 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
126
3797
54fd4d3b4fce Generate docs for help topics
Matt Mackall <mpm@selenic.com>
parents: 1814
diff changeset
127
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
128 if __name__ == "__main__":
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
129 show_doc(sys.stdout)