← 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

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2007-03-28 06:58:22 UTC
  • mfrom: (2379.2.3 hpss-chroot)
  • Revision ID: pqm@pqm.ubuntu.com-20070328065822-999550a858a3ced3
(robertc) Fix chroot urls to not expose the url of the transport they are protecting, allowing regular url operations to work on them. (Robert Collins, Andrew Bennetts)

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
120
                l += (30 - len(l)) * ' ' + (help or '')
144
121
                wrapped = textwrap.fill(l, initial_indent='',
145
 
                    subsequent_indent=30*' ',
146
 
                    break_long_words=False,
147
 
                    )
148
 
                option_str += wrapped + '\n'
 
122
                                        subsequent_indent=30*' ')
 
123
                option_str = option_str + wrapped + '\n'       
149
124
 
150
125
    aliases_str = ""
151
126
    if cmd.aliases:
156
131
        aliases_str += ', '.join(cmd.aliases)
157
132
        aliases_str += '\n'
158
133
 
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"
 
134
    return subsection_header + option_str + aliases_str + "\n" + doc + "\n"
183
135
 
184
136
 
185
137
man_preamble = """\
186
 
.\\\"Man page for Bazaar (%(bzrcmd)s)
 
138
Man page for Bazaar (%(bzrcmd)s)
187
139
.\\\"
188
140
.\\\" Large parts of this file are autogenerated from the output of
189
141
.\\\"     \"%(bzrcmd)s help commands\"
190
142
.\\\"     \"%(bzrcmd)s help <cmd>\"
191
143
.\\\"
192
 
 
193
 
.ie \\n(.g .ds Aq \\(aq
194
 
.el .ds Aq '
 
144
.\\\" Generation time: %(timestamp)s
 
145
.\\\"
195
146
"""
196
147
 
197
148
 
198
149
man_head = """\
199
150
.TH bzr 1 "%(datestamp)s" "%(version)s" "Bazaar"
200
151
.SH "NAME"
201
 
%(bzrcmd)s - Bazaar next-generation distributed version control
 
152
Bazaar (%(bzrcmd)s) - next-generation distributed version control
202
153
.SH "SYNOPSIS"
203
154
.B "%(bzrcmd)s"
204
155
.I "command"
213
164
.B "help"
214
165
.I "command"
215
166
.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.
 
167
Bazaar (or %(bzrcmd)s) is a project of Canonical to develop an open source
 
168
distributed version control system that is powerful, friendly, and scalable.
 
169
Version control means a system that keeps track of previous revisions
 
170
of software source code or similar information and helps people work on it in teams.
224
171
"""
225
172
 
226
173
man_foot = """\
 
174
.SH "ENVIRONMENT"
 
175
.TP
 
176
.I "BZRPATH"
 
177
Path where
 
178
.B "%(bzrcmd)s"
 
179
is to look for shell plugin external commands.
 
180
.TP
 
181
.I "BZR_EMAIL"
 
182
E-Mail address of the user. Overrides default user config.
 
183
.TP
 
184
.I "EMAIL"
 
185
E-Mail address of the user. Overrides default user config.
 
186
.TP
 
187
.I "BZR_EDITOR"
 
188
Editor for editing commit messages
 
189
.TP
 
190
.I "EDITOR"
 
191
Editor for editing commit messages
 
192
.TP
 
193
.I "BZR_PLUGIN_PATH"
 
194
Paths where bzr should look for plugins
 
195
.TP
 
196
.I "BZR_HOME"
 
197
Home directory for bzr
227
198
.SH "FILES"
228
199
.TP
229
200
.I "~/.bazaar/bazaar.conf"
248
219
.br
249
220
log10 = log --short -r -10..-1
250
221
.SH "SEE ALSO"
251
 
.UR http://bazaar.canonical.com/
252
 
.BR http://bazaar.canonical.com/
 
222
.UR http://www.bazaar-vcs.org/
 
223
.BR http://www.bazaar-vcs.org/
253
224
"""
254
225