← 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

  • Committer: Patch Queue Manager
  • Date: 2013-05-23 10:35:23 UTC
  • mfrom: (6574.1.1 integration)
  • Revision ID: pqm@pqm.ubuntu.com-20130523103523-2wt6jmauja1n1vdt
(jameinel) Merge bzr/2.5 into trunk. (John A Meinel)

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.
 
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.
162
226
"""
163
227
 
164
228
man_foot = """\
165
 
.SH "ENVIRONMENT"
166
 
.TP
167
 
.I "BZRPATH"
168
 
Path where
169
 
.B "%(bzrcmd)s"
170
 
is to look for external command.
171
 
.TP
172
 
.I "BZREMAIL"
173
 
E-Mail address of the user. Overrides default user config.
174
 
.TP
175
 
.I "EMAIL"
176
 
E-Mail address of the user. Overriddes default user config.
177
229
.SH "FILES"
178
230
.TP
179
 
.I "~/.bazaar/bazaar.conf/"
180
 
Contains the default user config. Only one section, [DEFAULT] is allowed. A 
181
 
typical default config file may be similiar to:
182
 
.br
183
 
.br
 
231
.I "~/.bazaar/bazaar.conf"
 
232
Contains the user's default configuration. The section
184
233
.B [DEFAULT]
185
 
.br
186
 
.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
187
252
.SH "SEE ALSO"
188
 
.UR http://www.bazaar-vcs.org/
189
 
.BR http://www.bazaar-vcs.org/
 
253
.UR http://bazaar.canonical.com/
 
254
.BR http://bazaar.canonical.com/
190
255
"""
191
256