← 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

Show diffs side-by-side

added added

removed removed

Lines of Context:
tools/doc_generate/autodoc_man.py
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
 
28
28
 
29
29
import bzrlib
30
30
import bzrlib.help
31
 
import bzrlib.help_topics
32
31
import bzrlib.commands
33
32
 
34
33
 
81
80
        cmd_help = cmd_object.help()
82
81
        if cmd_help:
83
82
            firstline = cmd_help.split('\n', 1)[0]
84
 
            usage = cmd_object._usage()
 
83
            usage = bzrlib.help.command_usage(cmd_object)
85
84
            tmp = '.TP\n.B "%s"\n%s\n' % (usage, firstline)
86
85
            output = output + tmp
87
86
        else:
92
91
def getcommand_help(params):
93
92
    """Shows individual options for a bzr command"""
94
93
    output='.SH "COMMAND REFERENCE"\n'
95
 
    formatted = {}
96
94
    for cmd_name in command_name_list():
97
95
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
98
96
        if cmd_object.hidden:
99
97
            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]
 
98
        output = output + format_command(params, cmd_object)
105
99
    return output
106
100
 
107
101
 
108
102
def format_command (params, cmd):
109
103
    """Provides long help for each public command"""
110
 
    subsection_header = '.SS "%s"\n' % (cmd._usage())
 
104
    subsection_header = '.SS "%s"\n' % (bzrlib.help.command_usage(cmd))
111
105
    doc = "%s\n" % (cmd.__doc__)
112
 
    doc = bzrlib.help_topics.help_as_plain_text(cmd.help())
 
106
    docsplit = cmd.__doc__.split('\n')
 
107
    doc = '\n'.join([docsplit[0]] + [line[4:] for line in docsplit[1:]])
113
108
 
114
109
    option_str = ""
115
110
    options = cmd.options()
116
111
    if options:
117
112
        option_str = "\nOptions:\n"
118
113
        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
 
                    assert len(short_name) == 1
127
 
                    l += ', -' + short_name
128
 
                l += (30 - len(l)) * ' ' + (help or '')
129
 
                wrapped = textwrap.fill(l, initial_indent='',
130
 
                                        subsequent_indent=30*' ')
131
 
                option_str = option_str + wrapped + '\n'       
 
114
            l = '    --' + option_name
 
115
            if option.type is not None:
 
116
                l += ' ' + option.argname.upper()
 
117
            short_name = option.short_name()
 
118
            if short_name:
 
119
                assert len(short_name) == 1
 
120
                l += ', -' + short_name
 
121
            l += (30 - len(l)) * ' ' + option.help
 
122
            # TODO: Split help over multiple lines with
 
123
            # correct indenting and wrapping.
 
124
            wrapped = textwrap.fill(l, initial_indent='',
 
125
                                    subsequent_indent=30*' ')
 
126
            option_str = option_str + wrapped + '\n'       
132
127
 
133
128
    aliases_str = ""
134
129
    if cmd.aliases:
139
134
        aliases_str += ', '.join(cmd.aliases)
140
135
        aliases_str += '\n'
141
136
 
142
 
    see_also_str = ""
143
 
    see_also = cmd.get_see_also()
144
 
    if see_also:
145
 
        see_also_str += '\nSee also: '
146
 
        see_also_str += ', '.join(see_also)
147
 
        see_also_str += '\n'
148
 
 
149
 
    return subsection_header + option_str + aliases_str + see_also_str + "\n" + doc + "\n"
150
 
 
151
 
 
152
 
def format_alias(params, alias, cmd_name):
153
 
    help = '.SS "bzr %s"\n' % alias
154
 
    help += 'Alias for "%s", see "bzr %s".\n' % (cmd_name, cmd_name)
155
 
    return help
 
137
    return subsection_header + option_str + aliases_str + "\n" + doc + "\n"
156
138
 
157
139
 
158
140
man_preamble = """\
159
 
.\\\"Man page for Bazaar (%(bzrcmd)s)
 
141
Man page for %(bzrcmd)s (bazaar-ng)
160
142
.\\\"
161
143
.\\\" Large parts of this file are autogenerated from the output of
162
144
.\\\"     \"%(bzrcmd)s help commands\"
168
150
 
169
151
 
170
152
man_head = """\
171
 
.TH bzr 1 "%(datestamp)s" "%(version)s" "Bazaar"
 
153
.TH bzr 1 "%(datestamp)s" "%(version)s" "bazaar-ng"
172
154
.SH "NAME"
173
 
Bazaar (%(bzrcmd)s) - next-generation distributed version control
 
155
%(bzrcmd)s - bazaar-ng next-generation distributed version control
174
156
.SH "SYNOPSIS"
175
157
.B "%(bzrcmd)s"
176
158
.I "command"
185
167
.B "help"
186
168
.I "command"
187
169
.SH "DESCRIPTION"
188
 
Bazaar (or %(bzrcmd)s) is a project of Canonical to develop an open source
189
 
distributed version control system that is powerful, friendly, and scalable.
190
 
Version control means a system that keeps track of previous revisions
191
 
of software source code or similar information and helps people work on it in teams.
 
170
bazaar-ng (or
 
171
.B "%(bzrcmd)s"
 
172
) 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.
192
173
"""
193
174
 
194
175
man_foot = """\
197
178
.I "BZRPATH"
198
179
Path where
199
180
.B "%(bzrcmd)s"
200
 
is to look for shell plugin external commands.
 
181
is to look for external command.
201
182
.TP
202
 
.I "BZR_EMAIL"
 
183
.I "BZREMAIL"
203
184
E-Mail address of the user. Overrides default user config.
204
185
.TP
205
186
.I "EMAIL"
206
 
E-Mail address of the user. Overrides default user config.
 
187
E-Mail address of the user. Overriddes default user config.
207
188
.TP
208
189
.I "BZR_EDITOR"
209
190
Editor for editing commit messages
219
200
.SH "FILES"
220
201
.TP
221
202
.I "~/.bazaar/bazaar.conf"
222
 
Contains the user's default configuration. The section
 
203
Contains the default user config. At least one section, [DEFAULT] is required.
 
204
A typical default config file may be similiar to:
 
205
.br
 
206
.br
223
207
.B [DEFAULT]
224
 
is used to define general configuration that will be applied everywhere.
225
 
The section
226
 
.B [ALIASES]
227
 
can be used to create command aliases for
228
 
commonly used options.
229
 
 
230
 
A typical config file might look something like:
231
 
 
232
 
.br
233
 
[DEFAULT]
234
 
.br
235
 
email=John Doe <jdoe@isp.com>
236
 
.br
237
 
[ALIASES]
238
 
.br
239
 
commit = commit --strict
240
 
.br
241
 
log10 = log --short -r -10..-1
 
208
.br
 
209
.B email=John Doe <jdoe@isp.com>
242
210
.SH "SEE ALSO"
243
211
.UR http://www.bazaar-vcs.org/
244
212
.BR http://www.bazaar-vcs.org/