3
# Copyright (C) 2005 by Hans Ulrich Niedermann
4
# Portions Copyright (C) 2005 by Canonical Ltd
1
# Copyright 2005 Canonical Ltd.
6
3
# This program is free software; you can redistribute it and/or modify
7
4
# it under the terms of the GNU General Public License as published by
8
5
# the Free Software Foundation; either version 2 of the License, or
9
6
# (at your option) any later version.
11
8
# This program is distributed in the hope that it will be useful,
12
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
13
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14
11
# GNU General Public License for more details.
16
13
# You should have received a copy of the GNU General Public License
17
14
# along with this program; if not, write to the Free Software
18
15
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20
#<<< code taken from bzr (C) Canonical
25
version_info = sys.version_info
26
except AttributeError:
27
version_info = 1, 5 # 1.5 or older
30
REINVOKE = "__BZR_REINVOKE"
33
if version_info < NEED_VERS:
34
if not os.environ.has_key(REINVOKE):
35
# mutating os.environ doesn't work in old Pythons
36
os.putenv(REINVOKE, "1")
37
for python in 'python2.4', 'python2.3':
39
os.execvp(python, [python] + sys.argv)
42
print >>sys.stderr, "bzr-man.py: error: cannot find a suitable python interpreter"
43
print >>sys.stderr, " (need %d.%d or later)" % NEED_VERS
47
import bzrlib, bzrlib.help
49
#>>> code taken from bzr (C) Canonical
17
"""man.py - create man page from built-in bzr help and static text
20
* use usage information instead of simple "bzr foo" in COMMAND OVERVIEW
31
import bzrlib.help_topics
32
import bzrlib.commands
35
def get_filename(options):
36
"""Provides name of manpage"""
37
return "%s.1" % (options.bzr_name)
40
def infogen(options, outfile):
41
"""Assembles a man page"""
45
{ "bzrcmd": options.bzr_name,
46
"datestamp": time.strftime("%Y-%m-%d",tt),
47
"timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
48
"version": bzrlib.__version__,
50
outfile.write(man_preamble % params)
51
outfile.write(man_escape(man_head % params))
52
outfile.write(man_escape(getcommand_list(params)))
53
outfile.write(man_escape(getcommand_help(params)))
54
outfile.write(man_escape(man_foot % params))
57
57
def man_escape(string):
58
"""Escapes strings for man page compatibility"""
58
59
result = string.replace("\\","\\\\")
59
60
result = result.replace("`","\\`")
60
61
result = result.replace("'","\\'")
67
def parse_line(self, line):
71
class CommandListParser(Parser):
73
"""Parser for output of "bzr help commands".
75
The parsed content can then be used to
76
- write a "COMMAND OVERVIEW" section into a man page
77
- provide a list of all commands
80
def __init__(self,params):
82
self.command_usage = []
83
self.all_commands = []
84
self.usage_exp = re.compile("([a-z0-9-]+).*")
85
self.descr_exp = re.compile(" ([A-Z].*)\s*")
91
def parse_line(self, line):
92
m = self.usage_exp.match(line)
96
self.command_usage.append((self.command,self.usage,self.descr))
97
self.all_commands.append(self.command)
99
self.command = m.groups()[0]
101
raise Error, "matching usage line in state %d" % state
104
m = self.descr_exp.match(line)
107
self.descr = m.groups()[0]
109
raise Error, "matching descr line in state %d" % state
112
raise Error, "Cannot parse this line"
117
self.command_usage.append((self.command,self.usage,self.descr))
118
self.all_commands.append(self.command)
120
raise Error, "ending parse in state %d" % state
122
def write_to_manpage(self, outfile):
123
bzrcmd = self.params["bzrcmd"]
124
outfile.write('.SH "COMMAND OVERVIEW"\n')
125
for (command,usage,descr) in self.command_usage:
126
outfile.write('.TP\n.B "%s %s"\n%s\n\n' % (bzrcmd, usage, descr))
131
def __init__(self, parser):
134
def write(self, data):
137
for line in data.split('\n'):
138
self.parser.parse_line(line)
141
def write_command_details(params, command, usage, descr, outfile):
142
x = ('.SS "%s %s"\n.B "%s"\n.PP\n.B "Usage:"\n%s %s\n\n' %
148
outfile.write(man_escape(x))
66
def command_name_list():
67
"""Builds a list of command names from bzrlib"""
68
command_names = bzrlib.commands.builtin_command_names()
73
def getcommand_list (params):
74
"""Builds summary help for command names in manpage format"""
75
bzrcmd = params["bzrcmd"]
76
output = '.SH "COMMAND OVERVIEW"\n'
77
for cmd_name in command_name_list():
78
cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
81
cmd_help = cmd_object.help()
83
firstline = cmd_help.split('\n', 1)[0]
84
usage = cmd_object._usage()
85
tmp = '.TP\n.B "%s"\n%s\n' % (usage, firstline)
88
raise RuntimeError, "Command '%s' has no help text" % (cmd_name)
92
def getcommand_help(params):
93
"""Shows individual options for a bzr command"""
94
output='.SH "COMMAND REFERENCE"\n'
95
for cmd_name in command_name_list():
96
cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
99
output = output + format_command(params, cmd_object)
103
def format_command (params, cmd):
104
"""Provides long help for each public command"""
105
subsection_header = '.SS "%s"\n' % (cmd._usage())
106
doc = "%s\n" % (cmd.__doc__)
107
doc = bzrlib.help_topics.help_as_plain_text(cmd.help())
110
options = cmd.options()
112
option_str = "\nOptions:\n"
113
for option_name, option in sorted(options.items()):
114
for name, short_name, argname, help in option.iter_switches():
115
if option.is_hidden(name):
118
if argname is not None:
121
assert len(short_name) == 1
122
l += ', -' + short_name
123
l += (30 - len(l)) * ' ' + (help or '')
124
wrapped = textwrap.fill(l, initial_indent='',
125
subsequent_indent=30*' ')
126
option_str = option_str + wrapped + '\n'
130
if len(cmd.aliases) > 1:
131
aliases_str += '\nAliases: '
133
aliases_str += '\nAlias: '
134
aliases_str += ', '.join(cmd.aliases)
138
see_also = cmd.get_see_also()
140
see_also_str += '\nSee also: '
141
see_also_str += ', '.join(see_also)
144
return subsection_header + option_str + aliases_str + see_also_str + "\n" + doc + "\n"
151
147
man_preamble = """\
152
.\\\" Man page for %(bzrcmd)s (bazaar-ng)
148
Man page for Bazaar (%(bzrcmd)s)
154
150
.\\\" Large parts of this file are autogenerated from the output of
155
151
.\\\" \"%(bzrcmd)s help commands\"
195
is to look for external command.
189
is to look for shell plugin external commands.
199
E-Mail address of the user. Overrides
200
.I "~/.bzr.conf/email" and
203
.I "John Doe <john@example.com>"
192
E-Mail address of the user. Overrides default user config.
207
E-Mail address of the user. Overridden by the content of the file
208
.I "~/.bzr.conf/email"
209
and of the environment variable
195
E-Mail address of the user. Overrides default user config.
198
Editor for editing commit messages
201
Editor for editing commit messages
204
Paths where bzr should look for plugins
207
Home directory for bzr
215
Directory where all the user\'s settings are stored.
217
.I "~/.bzr.conf/email"
218
Stores name and email address of the user. Overrides content of
220
environment variable. Example content:
221
.I "John Doe <john@example.com>"
210
.I "~/.bazaar/bazaar.conf"
211
Contains the user's default configuration. The section
213
is used to define general configuration that will be applied everywhere.
216
can be used to create command aliases for
217
commonly used options.
219
A typical config file might look something like:
224
email=John Doe <jdoe@isp.com>
228
commit = commit --strict
230
log10 = log --short -r -10..-1
224
.UR http://www.bazaar-ng.org/
225
.BR http://www.bazaar-ng.org/,
226
.UR http://www.bazaar-ng.org/doc/
227
.BR http://www.bazaar-ng.org/doc/
232
.UR http://www.bazaar-vcs.org/
233
.BR http://www.bazaar-vcs.org/
235
"datestamp": time.strftime("%Y-%m-%d",tt),
236
"timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
237
"version": bzrlib.__version__,
240
clp = CommandListParser(params)
241
bzrlib.help.help("commands", outfile=HelpReader(clp))
245
if len(sys.argv) == 2:
246
filename = sys.argv[1]
250
outfile = open(filename,"w")
252
outfile.write(man_preamble % params)
253
outfile.write(man_escape(man_head % params))
254
clp.write_to_manpage(outfile)
257
# This doesn't do more than the summary so far.
258
#outfile.write('.SH "DETAILED COMMAND DESCRIPTION"\n')
259
#for (command,usage,descr) in clp.command_usage:
260
# write_command_details(params, command, usage, descr, outfile = outfile)
262
outfile.write(man_escape(man_foot % params))
265
if __name__ == '__main__':
added
removed
tools/doc_generate/autodoc_man.py
