← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to tools/doc_generate/autodoc_man.py

[merge] Storage filename escaping

Show diffs side-by-side

added added

removed removed

Lines of Context:
tools/doc_generate/autodoc_man.py
1
 
# Copyright (C) 2005-2010 Canonical Ltd
 
1
# Copyright 2005 Canonical Ltd.
2
2
 
3
3
# This program is free software; you can redistribute it and/or modify
4
4
# it under the terms of the GNU General Public License as published by
5
5
# the Free Software Foundation; either version 2 of the License, or
6
6
# (at your option) any later version.
7
 
#
 
7
 
8
8
# This program is distributed in the hope that it will be useful,
9
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11
11
# GNU General Public License for more details.
12
 
#
 
12
 
13
13
# You should have received a copy of the GNU General Public License
14
14
# along with this program; if not, write to the Free Software
15
 
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
15
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16
16
 
17
17
"""man.py - create man page from built-in bzr help and static text
18
18
 
28
28
 
29
29
import bzrlib
30
30
import bzrlib.help
31
 
import bzrlib.help_topics
32
31
import bzrlib.commands
33
32
 
34
33
 
81
80
        cmd_help = cmd_object.help()
82
81
        if cmd_help:
83
82
            firstline = cmd_help.split('\n', 1)[0]
84
 
            usage = cmd_object._usage()
 
83
            usage = bzrlib.help.command_usage(cmd_object)
85
84
            tmp = '.TP\n.B "%s"\n%s\n' % (usage, firstline)
86
85
            output = output + tmp
87
86
        else:
92
91
def getcommand_help(params):
93
92
    """Shows individual options for a bzr command"""
94
93
    output='.SH "COMMAND REFERENCE"\n'
95
 
    formatted = {}
96
94
    for cmd_name in command_name_list():
97
95
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
98
96
        if cmd_object.hidden:
99
97
            continue
100
 
        formatted[cmd_name] = format_command(params, cmd_object)
101
 
        for alias in cmd_object.aliases:
102
 
            formatted[alias] = format_alias(params, alias, cmd_name)
103
 
    for cmd_name in sorted(formatted):
104
 
        output += formatted[cmd_name]
 
98
        output = output + format_command(params, cmd_object)
105
99
    return output
106
100
 
107
101
 
108
102
def format_command (params, cmd):
109
103
    """Provides long help for each public command"""
110
 
    subsection_header = '.SS "%s"\n' % (cmd._usage())
 
104
    subsection_header = '.SS "%s"\n' % (bzrlib.help.command_usage(cmd))
111
105
    doc = "%s\n" % (cmd.__doc__)
112
 
    doc = bzrlib.help_topics.help_as_plain_text(cmd.help())
113
 
 
 
106
    docsplit = cmd.__doc__.split('\n')
 
107
    doc = '\n'.join([docsplit[0]] + [line[4:] for line in docsplit[1:]])
114
108
    option_str = ""
115
109
    options = cmd.options()
116
110
    if options:
117
111
        option_str = "\nOptions:\n"
118
112
        for option_name, option in sorted(options.items()):
119
 
            for name, short_name, argname, help in option.iter_switches():
120
 
                if option.is_hidden(name):
121
 
                    continue
122
 
                l = '    --' + name
123
 
                if argname is not None:
124
 
                    l += ' ' + argname
125
 
                if short_name:
126
 
                    l += ', -' + short_name
127
 
                l += (30 - len(l)) * ' ' + (help or '')
128
 
                wrapped = textwrap.fill(l, initial_indent='',
129
 
                    subsequent_indent=30*' ',
130
 
                    break_long_words=False,
131
 
                    )
132
 
                option_str = option_str + wrapped + '\n'       
133
 
 
134
 
    aliases_str = ""
135
 
    if cmd.aliases:
136
 
        if len(cmd.aliases) > 1:
137
 
            aliases_str += '\nAliases: '
138
 
        else:
139
 
            aliases_str += '\nAlias: '
140
 
        aliases_str += ', '.join(cmd.aliases)
141
 
        aliases_str += '\n'
142
 
 
143
 
    see_also_str = ""
144
 
    see_also = cmd.get_see_also()
145
 
    if see_also:
146
 
        see_also_str += '\nSee also: '
147
 
        see_also_str += ', '.join(see_also)
148
 
        see_also_str += '\n'
149
 
 
150
 
    return subsection_header + option_str + aliases_str + see_also_str + "\n" + doc + "\n"
151
 
 
152
 
 
153
 
def format_alias(params, alias, cmd_name):
154
 
    help = '.SS "bzr %s"\n' % alias
155
 
    help += 'Alias for "%s", see "bzr %s".\n' % (cmd_name, cmd_name)
156
 
    return help
 
113
            l = '    --' + option_name
 
114
            if option.type is not None:
 
115
                l += ' ' + option.argname.upper()
 
116
            short_name = option.short_name()
 
117
            if short_name:
 
118
                assert len(short_name) == 1
 
119
                l += ', -' + short_name
 
120
            l += (30 - len(l)) * ' ' + option.help
 
121
            # TODO: Split help over multiple lines with
 
122
            # correct indenting and wrapping.
 
123
            wrapped = textwrap.fill(l, initial_indent='',
 
124
                                    subsequent_indent=30*' ')
 
125
            option_str = option_str + wrapped + '\n'       
 
126
    return subsection_header + option_str + "\n" + doc + "\n"
157
127
 
158
128
 
159
129
man_preamble = """\
160
 
.\\\"Man page for Bazaar (%(bzrcmd)s)
 
130
Man page for %(bzrcmd)s (bazaar-ng)
161
131
.\\\"
162
132
.\\\" Large parts of this file are autogenerated from the output of
163
133
.\\\"     \"%(bzrcmd)s help commands\"
169
139
 
170
140
 
171
141
man_head = """\
172
 
.TH bzr 1 "%(datestamp)s" "%(version)s" "Bazaar"
 
142
.TH bzr 1 "%(datestamp)s" "%(version)s" "bazaar-ng"
173
143
.SH "NAME"
174
 
%(bzrcmd)s - Bazaar next-generation distributed version control
 
144
%(bzrcmd)s - bazaar-ng next-generation distributed version control
175
145
.SH "SYNOPSIS"
176
146
.B "%(bzrcmd)s"
177
147
.I "command"
186
156
.B "help"
187
157
.I "command"
188
158
.SH "DESCRIPTION"
189
 
Bazaar (or %(bzrcmd)s) is a project of Canonical to develop an free
190
 
distributed version control system that is powerful, friendly, and scalable.
191
 
Version control means a system that keeps track of previous revisions
192
 
of software source code or similar information and helps people work on it in teams.
 
159
bazaar-ng (or
 
160
.B "%(bzrcmd)s"
 
161
) is a project of Canonical to develop an open source distributed version control system that is powerful, friendly, and scalable. Version control means a system that keeps track of previous revisions of software source code or similar information and helps people work on it in teams.
 
162
.SS "Warning"
 
163
bazaar-ng is at an early stage of development, and the design is still changing from week to week. This man page here may be inconsistent with itself, with other documentation or with the code, and sometimes refer to features that are planned but not yet written. Comments are still very welcome; please send them to bazaar-ng@lists.canonical.com.
193
164
"""
194
165
 
195
166
man_foot = """\
198
169
.I "BZRPATH"
199
170
Path where
200
171
.B "%(bzrcmd)s"
201
 
is to look for shell plugin external commands.
 
172
is to look for external command.
202
173
.TP
203
 
.I "BZR_EMAIL"
 
174
.I "BZREMAIL"
204
175
E-Mail address of the user. Overrides default user config.
205
176
.TP
206
177
.I "EMAIL"
207
 
E-Mail address of the user. Overrides default user config.
208
 
.TP
209
 
.I "BZR_EDITOR"
210
 
Editor for editing commit messages
211
 
.TP
212
 
.I "EDITOR"
213
 
Editor for editing commit messages
214
 
.TP
215
 
.I "BZR_PLUGIN_PATH"
216
 
Paths where bzr should look for plugins
217
 
.TP
218
 
.I "BZR_HOME"
219
 
Home directory for bzr
 
178
E-Mail address of the user. Overriddes default user config.
220
179
.SH "FILES"
221
180
.TP
222
 
.I "~/.bazaar/bazaar.conf"
223
 
Contains the user's default configuration. The section
 
181
.I "~/.bazaar/bazaar.conf/"
 
182
Contains the default user config. Only one section, [DEFAULT] is allowed. A 
 
183
typical default config file may be similiar to:
 
184
.br
 
185
.br
224
186
.B [DEFAULT]
225
 
is used to define general configuration that will be applied everywhere.
226
 
The section
227
 
.B [ALIASES]
228
 
can be used to create command aliases for
229
 
commonly used options.
230
 
 
231
 
A typical config file might look something like:
232
 
 
233
 
.br
234
 
[DEFAULT]
235
 
.br
236
 
email=John Doe <jdoe@isp.com>
237
 
.br
238
 
[ALIASES]
239
 
.br
240
 
commit = commit --strict
241
 
.br
242
 
log10 = log --short -r -10..-1
 
187
.br
 
188
.B email=John Doe <jdoe@isp.com>
243
189
.SH "SEE ALSO"
244
 
.UR http://www.bazaar.canonical.com/
245
 
.BR http://www.bazaar.canonical.com/
 
190
.UR http://bazaar.canonical.com/
 
191
.BR http://bazaar.canonical.com/,
 
192
.UR http://www.bazaar-ng.org/
 
193
.BR http://www.bazaar-ng.org/
246
194
"""
247
195