1
# Copyright 2006 Canonical Ltd.
3
# This program is free software; you can redistribute it and/or modify
4
# it under the terms of the GNU General Public License as published by
5
# the Free Software Foundation; either version 2 of the License, or
6
# (at your option) any later version.
8
# This program is distributed in the hope that it will be useful,
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11
# GNU General Public License for more details.
13
# You should have received a copy of the GNU General Public License
14
# along with this program; if not, write to the Free Software
15
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17
"""Generate ReStructuredText source for manual.
18
Based on manpage generator autodoc_man.py
20
Written by Alexander Belchenko
30
import bzrlib.commands
33
def get_filename(options):
34
"""Provides name of manual"""
35
return "%s_man.txt" % (options.bzr_name)
38
def infogen(options, outfile):
39
"""Create manual in RSTX format"""
43
{ "bzrcmd": options.bzr_name,
44
"datestamp": time.strftime("%Y-%m-%d",tt),
45
"timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
46
"version": bzrlib.__version__,
48
outfile.write(rstx_preamble % params)
49
outfile.write(rstx_head % params)
50
outfile.write(getcommand_list(params))
51
outfile.write(getcommand_help(params))
52
outfile.write(rstx_foot % params)
55
def command_name_list():
56
"""Builds a list of command names from bzrlib"""
57
command_names = bzrlib.commands.builtin_command_names()
62
def getcommand_list (params):
63
"""Builds summary help for command names in RSTX format"""
64
bzrcmd = params["bzrcmd"]
69
for cmd_name in command_name_list():
70
cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
73
cmd_help = cmd_object.help()
75
firstline = cmd_help.split('\n', 1)[0]
76
usage = bzrlib.help.command_usage(cmd_object)
77
tmp = '**%s**\n\t%s\n\n' % (usage, firstline)
80
raise RuntimeError, "Command '%s' has no help text" % (cmd_name)
84
def getcommand_help(params):
85
"""Shows individual options for a bzr command"""
90
for cmd_name in command_name_list():
91
cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
94
output = output + format_command(params, cmd_object, cmd_name)
98
def format_command (params, cmd, name):
99
"""Provides long help for each public command"""
100
usage = bzrlib.help.command_usage(cmd)
101
subsection_header = """
105
""" % (usage, '-'*len(usage))
107
docsplit = cmd.help().split('\n')
108
doc = '\n'.join([' '*4+line for line in docsplit])
111
options = cmd.options()
113
option_str = "\n Options:\n"
114
for option_name, option in sorted(options.items()):
115
for name, short_name, argname, help in option.iter_switches():
117
if argname is not None:
120
assert len(short_name) == 1
121
l += ', -' + short_name
122
l += (30 - len(l)) * ' ' + (help or '')
123
# TODO: Split help over multiple lines with
124
# correct indenting and wrapping.
125
wrapped = textwrap.fill(l, initial_indent='',
126
subsequent_indent=30*' ')
127
option_str = option_str + wrapped + '\n'
131
if len(cmd.aliases) > 1:
132
aliases_str += '\n Aliases: '
134
aliases_str += '\n Alias: '
135
aliases_str += ', '.join(cmd.aliases)
138
return subsection_header + option_str + aliases_str + "\n" + doc + "\n"
144
rstx_preamble = """.. Large parts of this file are autogenerated from the output of
145
.. %(bzrcmd)s help commands
146
.. %(bzrcmd)s help <cmd>
148
.. Generation time: %(timestamp)s
150
=============================================
151
Man page for Bazaar (%(bzrcmd)s)
152
=============================================
166
Bazaar (%(bzrcmd)s) - next-generation distributed version control
170
**%(bzrcmd)s** *command* [ *command_options* ]
174
**%(bzrcmd)s help** *command*
179
Bazaar (or **%(bzrcmd)s**) is a project of Canonical to develop
180
an open source distributed version control system that is powerful,
181
friendly, and scalable. Version control means a system
182
that keeps track of previous revisions of software source code
183
or similar information and helps people work on it in teams.
191
Path where **%(bzrcmd)s** is to look for shell plugin external commands.
194
E-Mail address of the user. Overrides default user config.
197
E-Mail address of the user. Overrides default user config.
200
Editor for editing commit messages
203
Editor for editing commit messages
206
Paths where bzr should look for plugins
209
Home directory for bzr
215
**On Linux**: ``~/.bazaar/bazaar.conf``
217
**On Windows**: ``C:\\Documents and Settings\\username\\Application Data\\bazaar\\2.0\\bazaar.conf``
219
Contains the user's default configuration. The section ``[DEFAULT]`` is
220
used to define general configuration that will be applied everywhere.
221
The section ``[ALIASES]`` can be used to create command aliases for
222
commonly used options.
224
A typical config file might look something like::
227
email=John Doe <jdoe@isp.com>
230
commit = commit --strict
231
log10 = log --short -r -10..-1
236
http://www.bazaar-vcs.org/
added
removed
tools/doc_generate/autodoc_rstx.py
