← 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: 2011-05-04 12:10:51 UTC
  • mfrom: (5819.1.4 777007-developer-doc)
  • Revision ID: pqm@pqm.ubuntu.com-20110504121051-aovlsmqiivjmc4fc
(jelmer) Small fixes to developer documentation. (Jonathan Riddell)

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
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
 
28
28
 
29
29
import bzrlib
30
30
import bzrlib.help
 
31
import bzrlib.help_topics
31
32
import bzrlib.commands
32
33
 
33
34
 
80
81
        cmd_help = cmd_object.help()
81
82
        if cmd_help:
82
83
            firstline = cmd_help.split('\n', 1)[0]
83
 
            usage = bzrlib.help.command_usage(cmd_object)
 
84
            usage = cmd_object._usage()
84
85
            tmp = '.TP\n.B "%s"\n%s\n' % (usage, firstline)
85
86
            output = output + tmp
86
87
        else:
91
92
def getcommand_help(params):
92
93
    """Shows individual options for a bzr command"""
93
94
    output='.SH "COMMAND REFERENCE"\n'
 
95
    formatted = {}
94
96
    for cmd_name in command_name_list():
95
97
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
96
98
        if cmd_object.hidden:
97
99
            continue
98
 
        output = output + format_command(params, cmd_object)
 
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]
99
105
    return output
100
106
 
101
107
 
102
108
def format_command (params, cmd):
103
109
    """Provides long help for each public command"""
104
 
    subsection_header = '.SS "%s"\n' % (bzrlib.help.command_usage(cmd))
 
110
    subsection_header = '.SS "%s"\n' % (cmd._usage())
105
111
    doc = "%s\n" % (cmd.__doc__)
106
 
    doc = cmd.help()
 
112
    doc = bzrlib.help_topics.help_as_plain_text(cmd.help())
107
113
 
108
114
    option_str = ""
109
115
    options = cmd.options()
111
117
        option_str = "\nOptions:\n"
112
118
        for option_name, option in sorted(options.items()):
113
119
            for name, short_name, argname, help in option.iter_switches():
 
120
                if option.is_hidden(name):
 
121
                    continue
114
122
                l = '    --' + name
115
123
                if argname is not None:
116
124
                    l += ' ' + argname
117
125
                if short_name:
118
 
                    assert len(short_name) == 1
119
126
                    l += ', -' + short_name
120
 
                l += (30 - len(l)) * ' ' + help
121
 
                # TODO: Split help over multiple lines with
122
 
                # correct indenting and wrapping.
 
127
                l += (30 - len(l)) * ' ' + (help or '')
123
128
                wrapped = textwrap.fill(l, initial_indent='',
124
 
                                        subsequent_indent=30*' ')
 
129
                    subsequent_indent=30*' ',
 
130
                    break_long_words=False,
 
131
                    )
125
132
                option_str = option_str + wrapped + '\n'       
126
133
 
127
134
    aliases_str = ""
133
140
        aliases_str += ', '.join(cmd.aliases)
134
141
        aliases_str += '\n'
135
142
 
136
 
    return subsection_header + option_str + aliases_str + "\n" + doc + "\n"
 
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
137
157
 
138
158
 
139
159
man_preamble = """\
140
 
Man page for Bazaar (%(bzrcmd)s)
 
160
.\\\"Man page for Bazaar (%(bzrcmd)s)
141
161
.\\\"
142
162
.\\\" Large parts of this file are autogenerated from the output of
143
163
.\\\"     \"%(bzrcmd)s help commands\"
151
171
man_head = """\
152
172
.TH bzr 1 "%(datestamp)s" "%(version)s" "Bazaar"
153
173
.SH "NAME"
154
 
Bazaar (%(bzrcmd)s) - next-generation distributed version control
 
174
%(bzrcmd)s - Bazaar next-generation distributed version control
155
175
.SH "SYNOPSIS"
156
176
.B "%(bzrcmd)s"
157
177
.I "command"
166
186
.B "help"
167
187
.I "command"
168
188
.SH "DESCRIPTION"
169
 
Bazaar (or %(bzrcmd)s) is a project of Canonical to develop an open source
 
189
Bazaar (or %(bzrcmd)s) is a project of Canonical to develop an free
170
190
distributed version control system that is powerful, friendly, and scalable.
171
191
Version control means a system that keeps track of previous revisions
172
192
of software source code or similar information and helps people work on it in teams.
178
198
.I "BZRPATH"
179
199
Path where
180
200
.B "%(bzrcmd)s"
181
 
is to look for external command.
 
201
is to look for shell plugin external commands.
182
202
.TP
183
203
.I "BZR_EMAIL"
184
204
E-Mail address of the user. Overrides default user config.
185
205
.TP
186
206
.I "EMAIL"
187
 
E-Mail address of the user. Overriddes default user config.
 
207
E-Mail address of the user. Overrides default user config.
188
208
.TP
189
209
.I "BZR_EDITOR"
190
210
Editor for editing commit messages
200
220
.SH "FILES"
201
221
.TP
202
222
.I "~/.bazaar/bazaar.conf"
203
 
Contains the users default configuration. The section
 
223
Contains the user's default configuration. The section
204
224
.B [DEFAULT]
205
225
is used to define general configuration that will be applied everywhere.
206
226
The section
221
241
.br
222
242
log10 = log --short -r -10..-1
223
243
.SH "SEE ALSO"
224
 
.UR http://www.bazaar-vcs.org/
225
 
.BR http://www.bazaar-vcs.org/
 
244
.UR http://bazaar.canonical.com/
 
245
.BR http://bazaar.canonical.com/
226
246
"""
227
247