← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/doc_generate/autodoc_man.py

(vila) Calling super() instead of mentioning the base class in setUp avoid
 mistakes. (Vincent Ladeuil)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/doc_generate/autodoc_man.py
1
 
# Copyright 2005 Canonical Ltd.
 
1
# Copyright (C) 2005-2010 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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16
16
 
17
17
"""man.py - create man page from built-in bzr help and static text
18
18
 
21
21
  * add command aliases
22
22
"""
23
23
 
24
 
import os
25
 
import sys
 
24
from __future__ import absolute_import
 
25
 
 
26
PLUGINS_TO_DOCUMENT = ["launchpad"]
 
27
 
26
28
import textwrap
27
29
import time
28
30
 
29
31
import bzrlib
30
32
import bzrlib.help
 
33
import bzrlib.help_topics
31
34
import bzrlib.commands
32
35
 
 
36
from bzrlib.plugin import load_plugins
 
37
load_plugins()
 
38
 
33
39
 
34
40
def get_filename(options):
35
41
    """Provides name of manpage"""
50
56
    outfile.write(man_escape(man_head % params))
51
57
    outfile.write(man_escape(getcommand_list(params)))
52
58
    outfile.write(man_escape(getcommand_help(params)))
 
59
    outfile.write("".join(environment_variables()))
53
60
    outfile.write(man_escape(man_foot % params))
54
61
 
55
62
 
56
63
def man_escape(string):
57
64
    """Escapes strings for man page compatibility"""
58
65
    result = string.replace("\\","\\\\")
59
 
    result = result.replace("`","\\`")
60
 
    result = result.replace("'","\\'")
 
66
    result = result.replace("`","\\'")
 
67
    result = result.replace("'","\\*(Aq")
61
68
    result = result.replace("-","\\-")
62
69
    return result
63
70
 
65
72
def command_name_list():
66
73
    """Builds a list of command names from bzrlib"""
67
74
    command_names = bzrlib.commands.builtin_command_names()
 
75
    for cmdname in bzrlib.commands.plugin_command_names():
 
76
        cmd_object = bzrlib.commands.get_cmd_object(cmdname)
 
77
        if (PLUGINS_TO_DOCUMENT is None or
 
78
            cmd_object.plugin_name() in PLUGINS_TO_DOCUMENT):
 
79
            command_names.append(cmdname)
68
80
    command_names.sort()
69
81
    return command_names
70
82
 
80
92
        cmd_help = cmd_object.help()
81
93
        if cmd_help:
82
94
            firstline = cmd_help.split('\n', 1)[0]
83
 
            usage = bzrlib.help.command_usage(cmd_object)
 
95
            usage = cmd_object._usage()
84
96
            tmp = '.TP\n.B "%s"\n%s\n' % (usage, firstline)
85
97
            output = output + tmp
86
98
        else:
91
103
def getcommand_help(params):
92
104
    """Shows individual options for a bzr command"""
93
105
    output='.SH "COMMAND REFERENCE"\n'
 
106
    formatted = {}
94
107
    for cmd_name in command_name_list():
95
108
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
96
109
        if cmd_object.hidden:
97
110
            continue
98
 
        output = output + format_command(params, cmd_object)
 
111
        formatted[cmd_name] = format_command(params, cmd_object)
 
112
        for alias in cmd_object.aliases:
 
113
            formatted[alias] = format_alias(params, alias, cmd_name)
 
114
    for cmd_name in sorted(formatted):
 
115
        output += formatted[cmd_name]
99
116
    return output
100
117
 
101
118
 
102
 
def format_command (params, cmd):
 
119
def format_command(params, cmd):
103
120
    """Provides long help for each public command"""
104
 
    subsection_header = '.SS "%s"\n' % (bzrlib.help.command_usage(cmd))
 
121
    subsection_header = '.SS "%s"\n' % (cmd._usage())
105
122
    doc = "%s\n" % (cmd.__doc__)
106
 
    docsplit = cmd.__doc__.split('\n')
107
 
    doc = '\n'.join([docsplit[0]] + [line[4:] for line in docsplit[1:]])
 
123
    doc = bzrlib.help_topics.help_as_plain_text(cmd.help())
 
124
 
 
125
    # A dot at the beginning of a line is interpreted as a macro.
 
126
    # Simply join lines that begin with a dot with the previous
 
127
    # line to work around this.
 
128
    doc = doc.replace("\n.", ".")
 
129
 
108
130
    option_str = ""
109
131
    options = cmd.options()
110
132
    if options:
111
133
        option_str = "\nOptions:\n"
112
134
        for option_name, option in sorted(options.items()):
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"
 
135
            for name, short_name, argname, help in option.iter_switches():
 
136
                if option.is_hidden(name):
 
137
                    continue
 
138
                l = '    --' + name
 
139
                if argname is not None:
 
140
                    l += ' ' + argname
 
141
                if short_name:
 
142
                    l += ', -' + short_name
 
143
                l += (30 - len(l)) * ' ' + (help or '')
 
144
                wrapped = textwrap.fill(l, initial_indent='',
 
145
                    subsequent_indent=30*' ',
 
146
                    break_long_words=False,
 
147
                    )
 
148
                option_str += wrapped + '\n'
 
149
 
 
150
    aliases_str = ""
 
151
    if cmd.aliases:
 
152
        if len(cmd.aliases) > 1:
 
153
            aliases_str += '\nAliases: '
 
154
        else:
 
155
            aliases_str += '\nAlias: '
 
156
        aliases_str += ', '.join(cmd.aliases)
 
157
        aliases_str += '\n'
 
158
 
 
159
    see_also_str = ""
 
160
    see_also = cmd.get_see_also()
 
161
    if see_also:
 
162
        see_also_str += '\nSee also: '
 
163
        see_also_str += ', '.join(see_also)
 
164
        see_also_str += '\n'
 
165
 
 
166
    return subsection_header + option_str + aliases_str + see_also_str + "\n" + doc + "\n"
 
167
 
 
168
 
 
169
def format_alias(params, alias, cmd_name):
 
170
    help = '.SS "bzr %s"\n' % alias
 
171
    help += 'Alias for "%s", see "bzr %s".\n' % (cmd_name, cmd_name)
 
172
    return help
 
173
 
 
174
 
 
175
def environment_variables():
 
176
    yield ".SH \"ENVIRONMENT\"\n"
 
177
 
 
178
    from bzrlib.help_topics import known_env_variables
 
179
    for k, desc in known_env_variables:
 
180
        yield ".TP\n"
 
181
        yield ".I \"%s\"\n" % k
 
182
        yield man_escape(desc) + "\n"
127
183
 
128
184
 
129
185
man_preamble = """\
130
 
Man page for %(bzrcmd)s (bazaar-ng)
 
186
.\\\"Man page for Bazaar (%(bzrcmd)s)
131
187
.\\\"
132
188
.\\\" Large parts of this file are autogenerated from the output of
133
189
.\\\"     \"%(bzrcmd)s help commands\"
135
191
.\\\"
136
192
.\\\" Generation time: %(timestamp)s
137
193
.\\\"
 
194
 
 
195
.ie \\n(.g .ds Aq \\(aq
 
196
.el .ds Aq '
138
197
"""
139
198
 
140
199
 
141
200
man_head = """\
142
 
.TH bzr 1 "%(datestamp)s" "%(version)s" "bazaar-ng"
 
201
.TH bzr 1 "%(datestamp)s" "%(version)s" "Bazaar"
143
202
.SH "NAME"
144
 
%(bzrcmd)s - bazaar-ng next-generation distributed version control
 
203
%(bzrcmd)s - Bazaar next-generation distributed version control
145
204
.SH "SYNOPSIS"
146
205
.B "%(bzrcmd)s"
147
206
.I "command"
156
215
.B "help"
157
216
.I "command"
158
217
.SH "DESCRIPTION"
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.
 
218
 
 
219
Bazaar (or %(bzrcmd)s) is a distributed version control system that is powerful, 
 
220
friendly, and scalable.  Bazaar is a project of Canonical Ltd and part of 
 
221
the GNU Project to develop a free operating system.
 
222
 
 
223
Bazaar keeps track of changes to software source code (or similar information);
 
224
lets you explore who changed it, when, and why; merges concurrent changes; and
 
225
helps people work together in a team.
164
226
"""
165
227
 
166
228
man_foot = """\
167
 
.SH "ENVIRONMENT"
168
 
.TP
169
 
.I "BZRPATH"
170
 
Path where
171
 
.B "%(bzrcmd)s"
172
 
is to look for external command.
173
 
.TP
174
 
.I "BZREMAIL"
175
 
E-Mail address of the user. Overrides default user config.
176
 
.TP
177
 
.I "EMAIL"
178
 
E-Mail address of the user. Overriddes default user config.
179
229
.SH "FILES"
180
230
.TP
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
 
231
.I "~/.bazaar/bazaar.conf"
 
232
Contains the user's default configuration. The section
186
233
.B [DEFAULT]
187
 
.br
188
 
.B email=John Doe <jdoe@isp.com>
 
234
is used to define general configuration that will be applied everywhere.
 
235
The section
 
236
.B [ALIASES]
 
237
can be used to create command aliases for
 
238
commonly used options.
 
239
 
 
240
A typical config file might look something like:
 
241
 
 
242
.br
 
243
[DEFAULT]
 
244
.br
 
245
email=John Doe <jdoe@isp.com>
 
246
.br
 
247
[ALIASES]
 
248
.br
 
249
commit = commit --strict
 
250
.br
 
251
log10 = log --short -r -10..-1
189
252
.SH "SEE ALSO"
190
253
.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/
 
254
.BR http://bazaar.canonical.com/
194
255
"""
195
256