← 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: Canonical.com Patch Queue Manager
  • Date: 2010-09-29 22:03:03 UTC
  • mfrom: (5416.2.6 jam-integration)
  • Revision ID: pqm@pqm.ubuntu.com-20100929220303-cr95h8iwtggco721
(mbp) Add 'break-lock --force'

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/doc_generate/autodoc_man.py
 
1
# Copyright (C) 2005-2010 Canonical Ltd
 
2
 
 
3
# This program is free software; you can redistribute it and/or modify
 
4
# it under the terms of the GNU General Public License as published by
 
5
# the Free Software Foundation; either version 2 of the License, or
 
6
# (at your option) any later version.
 
7
#
 
8
# This program is distributed in the hope that it will be useful,
 
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
 
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
11
# GNU General Public License for more details.
 
12
#
 
13
# You should have received a copy of the GNU General Public License
 
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
 
16
 
 
17
"""man.py - create man page from built-in bzr help and static text
 
18
 
 
19
TODO:
 
20
  * use usage information instead of simple "bzr foo" in COMMAND OVERVIEW
 
21
  * add command aliases
 
22
"""
 
23
 
 
24
import os
 
25
import sys
 
26
import textwrap
 
27
import time
 
28
 
 
29
import bzrlib
 
30
import bzrlib.help
 
31
import bzrlib.help_topics
 
32
import bzrlib.commands
 
33
 
 
34
 
 
35
def get_filename(options):
 
36
    """Provides name of manpage"""
 
37
    return "%s.1" % (options.bzr_name)
 
38
 
 
39
 
 
40
def infogen(options, outfile):
 
41
    """Assembles a man page"""
 
42
    t = time.time()
 
43
    tt = time.gmtime(t)
 
44
    params = \
 
45
           { "bzrcmd": options.bzr_name,
 
46
             "datestamp": time.strftime("%Y-%m-%d",tt),
 
47
             "timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
 
48
             "version": bzrlib.__version__,
 
49
             }
 
50
    outfile.write(man_preamble % params)
 
51
    outfile.write(man_escape(man_head % params))
 
52
    outfile.write(man_escape(getcommand_list(params)))
 
53
    outfile.write(man_escape(getcommand_help(params)))
 
54
    outfile.write(man_escape(man_foot % params))
 
55
 
 
56
 
 
57
def man_escape(string):
 
58
    """Escapes strings for man page compatibility"""
 
59
    result = string.replace("\\","\\\\")
 
60
    result = result.replace("`","\\`")
 
61
    result = result.replace("'","\\'")
 
62
    result = result.replace("-","\\-")
 
63
    return result
 
64
 
 
65
 
 
66
def command_name_list():
 
67
    """Builds a list of command names from bzrlib"""
 
68
    command_names = bzrlib.commands.builtin_command_names()
 
69
    command_names.sort()
 
70
    return command_names
 
71
 
 
72
 
 
73
def getcommand_list (params):
 
74
    """Builds summary help for command names in manpage format"""
 
75
    bzrcmd = params["bzrcmd"]
 
76
    output = '.SH "COMMAND OVERVIEW"\n'
 
77
    for cmd_name in command_name_list():
 
78
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
 
79
        if cmd_object.hidden:
 
80
            continue
 
81
        cmd_help = cmd_object.help()
 
82
        if cmd_help:
 
83
            firstline = cmd_help.split('\n', 1)[0]
 
84
            usage = cmd_object._usage()
 
85
            tmp = '.TP\n.B "%s"\n%s\n' % (usage, firstline)
 
86
            output = output + tmp
 
87
        else:
 
88
            raise RuntimeError, "Command '%s' has no help text" % (cmd_name)
 
89
    return output
 
90
 
 
91
 
 
92
def getcommand_help(params):
 
93
    """Shows individual options for a bzr command"""
 
94
    output='.SH "COMMAND REFERENCE"\n'
 
95
    formatted = {}
 
96
    for cmd_name in command_name_list():
 
97
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
 
98
        if cmd_object.hidden:
 
99
            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]
 
105
    return output
 
106
 
 
107
 
 
108
def format_command (params, cmd):
 
109
    """Provides long help for each public command"""
 
110
    subsection_header = '.SS "%s"\n' % (cmd._usage())
 
111
    doc = "%s\n" % (cmd.__doc__)
 
112
    doc = bzrlib.help_topics.help_as_plain_text(cmd.help())
 
113
 
 
114
    option_str = ""
 
115
    options = cmd.options()
 
116
    if options:
 
117
        option_str = "\nOptions:\n"
 
118
        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
 
157
 
 
158
 
 
159
man_preamble = """\
 
160
.\\\"Man page for Bazaar (%(bzrcmd)s)
 
161
.\\\"
 
162
.\\\" Large parts of this file are autogenerated from the output of
 
163
.\\\"     \"%(bzrcmd)s help commands\"
 
164
.\\\"     \"%(bzrcmd)s help <cmd>\"
 
165
.\\\"
 
166
.\\\" Generation time: %(timestamp)s
 
167
.\\\"
 
168
"""
 
169
 
 
170
 
 
171
man_head = """\
 
172
.TH bzr 1 "%(datestamp)s" "%(version)s" "Bazaar"
 
173
.SH "NAME"
 
174
%(bzrcmd)s - Bazaar next-generation distributed version control
 
175
.SH "SYNOPSIS"
 
176
.B "%(bzrcmd)s"
 
177
.I "command"
 
178
[
 
179
.I "command_options"
 
180
]
 
181
.br
 
182
.B "%(bzrcmd)s"
 
183
.B "help"
 
184
.br
 
185
.B "%(bzrcmd)s"
 
186
.B "help"
 
187
.I "command"
 
188
.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.
 
193
"""
 
194
 
 
195
man_foot = """\
 
196
.SH "ENVIRONMENT"
 
197
.TP
 
198
.I "BZRPATH"
 
199
Path where
 
200
.B "%(bzrcmd)s"
 
201
is to look for shell plugin external commands.
 
202
.TP
 
203
.I "BZR_EMAIL"
 
204
E-Mail address of the user. Overrides default user config.
 
205
.TP
 
206
.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
 
220
.SH "FILES"
 
221
.TP
 
222
.I "~/.bazaar/bazaar.conf"
 
223
Contains the user's default configuration. The section
 
224
.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
 
243
.SH "SEE ALSO"
 
244
.UR http://bazaar.canonical.com/
 
245
.BR http://bazaar.canonical.com/
 
246
"""
 
247