← 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 bzr.dev (and fix NEWS)

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
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
 
21
21
  * add command aliases
22
22
"""
23
23
 
24
 
from __future__ import absolute_import
25
 
 
26
 
PLUGINS_TO_DOCUMENT = ["launchpad"]
27
 
 
 
24
import os
 
25
import sys
28
26
import textwrap
29
27
import time
30
28
 
31
29
import bzrlib
32
30
import bzrlib.help
33
 
import bzrlib.help_topics
34
31
import bzrlib.commands
35
32
 
36
 
from bzrlib.plugin import load_plugins
37
 
load_plugins()
38
 
 
39
33
 
40
34
def get_filename(options):
41
35
    """Provides name of manpage"""
56
50
    outfile.write(man_escape(man_head % params))
57
51
    outfile.write(man_escape(getcommand_list(params)))
58
52
    outfile.write(man_escape(getcommand_help(params)))
59
 
    outfile.write("".join(environment_variables()))
60
53
    outfile.write(man_escape(man_foot % params))
61
54
 
62
55
 
63
56
def man_escape(string):
64
57
    """Escapes strings for man page compatibility"""
65
58
    result = string.replace("\\","\\\\")
66
 
    result = result.replace("`","\\'")
67
 
    result = result.replace("'","\\*(Aq")
 
59
    result = result.replace("`","\\`")
 
60
    result = result.replace("'","\\'")
68
61
    result = result.replace("-","\\-")
69
62
    return result
70
63
 
72
65
def command_name_list():
73
66
    """Builds a list of command names from bzrlib"""
74
67
    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)
80
68
    command_names.sort()
81
69
    return command_names
82
70
 
92
80
        cmd_help = cmd_object.help()
93
81
        if cmd_help:
94
82
            firstline = cmd_help.split('\n', 1)[0]
95
 
            usage = cmd_object._usage()
 
83
            usage = bzrlib.help.command_usage(cmd_object)
96
84
            tmp = '.TP\n.B "%s"\n%s\n' % (usage, firstline)
97
85
            output = output + tmp
98
86
        else:
103
91
def getcommand_help(params):
104
92
    """Shows individual options for a bzr command"""
105
93
    output='.SH "COMMAND REFERENCE"\n'
106
 
    formatted = {}
107
94
    for cmd_name in command_name_list():
108
95
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
109
96
        if cmd_object.hidden:
110
97
            continue
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]
 
98
        output = output + format_command(params, cmd_object)
116
99
    return output
117
100
 
118
101
 
119
 
def format_command(params, cmd):
 
102
def format_command (params, cmd):
120
103
    """Provides long help for each public command"""
121
 
    subsection_header = '.SS "%s"\n' % (cmd._usage())
 
104
    subsection_header = '.SS "%s"\n' % (bzrlib.help.command_usage(cmd))
122
105
    doc = "%s\n" % (cmd.__doc__)
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.", ".")
 
106
    doc = cmd.help()
129
107
 
130
108
    option_str = ""
131
109
    options = cmd.options()
133
111
        option_str = "\nOptions:\n"
134
112
        for option_name, option in sorted(options.items()):
135
113
            for name, short_name, argname, help in option.iter_switches():
136
 
                if option.is_hidden(name):
137
 
                    continue
138
114
                l = '    --' + name
139
115
                if argname is not None:
140
116
                    l += ' ' + argname
141
117
                if short_name:
 
118
                    assert len(short_name) == 1
142
119
                    l += ', -' + short_name
143
 
                l += (30 - len(l)) * ' ' + (help or '')
 
120
                l += (30 - len(l)) * ' ' + help
 
121
                # TODO: Split help over multiple lines with
 
122
                # correct indenting and wrapping.
144
123
                wrapped = textwrap.fill(l, initial_indent='',
145
 
                    subsequent_indent=30*' ',
146
 
                    break_long_words=False,
147
 
                    )
148
 
                option_str += wrapped + '\n'
 
124
                                        subsequent_indent=30*' ')
 
125
                option_str = option_str + wrapped + '\n'       
149
126
 
150
127
    aliases_str = ""
151
128
    if cmd.aliases:
156
133
        aliases_str += ', '.join(cmd.aliases)
157
134
        aliases_str += '\n'
158
135
 
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"
 
136
    return subsection_header + option_str + aliases_str + "\n" + doc + "\n"
183
137
 
184
138
 
185
139
man_preamble = """\
186
 
.\\\"Man page for Bazaar (%(bzrcmd)s)
 
140
Man page for Bazaar (%(bzrcmd)s)
187
141
.\\\"
188
142
.\\\" Large parts of this file are autogenerated from the output of
189
143
.\\\"     \"%(bzrcmd)s help commands\"
190
144
.\\\"     \"%(bzrcmd)s help <cmd>\"
191
145
.\\\"
192
 
 
193
 
.ie \\n(.g .ds Aq \\(aq
194
 
.el .ds Aq '
 
146
.\\\" Generation time: %(timestamp)s
 
147
.\\\"
195
148
"""
196
149
 
197
150
 
198
151
man_head = """\
199
152
.TH bzr 1 "%(datestamp)s" "%(version)s" "Bazaar"
200
153
.SH "NAME"
201
 
%(bzrcmd)s - Bazaar next-generation distributed version control
 
154
Bazaar (%(bzrcmd)s) - next-generation distributed version control
202
155
.SH "SYNOPSIS"
203
156
.B "%(bzrcmd)s"
204
157
.I "command"
213
166
.B "help"
214
167
.I "command"
215
168
.SH "DESCRIPTION"
216
 
 
217
 
Bazaar (or %(bzrcmd)s) is a distributed version control system that is powerful, 
218
 
friendly, and scalable.  Bazaar is a project of Canonical Ltd and part of 
219
 
the GNU Project to develop a free operating system.
220
 
 
221
 
Bazaar keeps track of changes to software source code (or similar information);
222
 
lets you explore who changed it, when, and why; merges concurrent changes; and
223
 
helps people work together in a team.
 
169
Bazaar (or %(bzrcmd)s) is a project of Canonical to develop an open source
 
170
distributed version control system that is powerful, friendly, and scalable.
 
171
Version control means a system that keeps track of previous revisions
 
172
of software source code or similar information and helps people work on it in teams.
224
173
"""
225
174
 
226
175
man_foot = """\
 
176
.SH "ENVIRONMENT"
 
177
.TP
 
178
.I "BZRPATH"
 
179
Path where
 
180
.B "%(bzrcmd)s"
 
181
is to look for external command.
 
182
.TP
 
183
.I "BZR_EMAIL"
 
184
E-Mail address of the user. Overrides default user config.
 
185
.TP
 
186
.I "EMAIL"
 
187
E-Mail address of the user. Overriddes default user config.
 
188
.TP
 
189
.I "BZR_EDITOR"
 
190
Editor for editing commit messages
 
191
.TP
 
192
.I "EDITOR"
 
193
Editor for editing commit messages
 
194
.TP
 
195
.I "BZR_PLUGIN_PATH"
 
196
Paths where bzr should look for plugins
 
197
.TP
 
198
.I "BZR_HOME"
 
199
Home directory for bzr
227
200
.SH "FILES"
228
201
.TP
229
202
.I "~/.bazaar/bazaar.conf"
230
 
Contains the user's default configuration. The section
 
203
Contains the users default configuration. The section
231
204
.B [DEFAULT]
232
205
is used to define general configuration that will be applied everywhere.
233
206
The section
248
221
.br
249
222
log10 = log --short -r -10..-1
250
223
.SH "SEE ALSO"
251
 
.UR http://bazaar.canonical.com/
252
 
.BR http://bazaar.canonical.com/
 
224
.UR http://www.bazaar-vcs.org/
 
225
.BR http://www.bazaar-vcs.org/
253
226
"""
254
227