/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to tools/doc_generate/autodoc_man.py

  • Committer: John Arbash Meinel
  • Date: 2006-04-25 15:05:42 UTC
  • mfrom: (1185.85.85 bzr-encoding)
  • mto: This revision was merged to the branch mainline in revision 1752.
  • Revision ID: john@arbash-meinel.com-20060425150542-c7b518dca9928691
[merge] the old bzr-encoding changes, reparenting them on bzr.dev

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
5
5
# the Free Software Foundation; either version 2 of the License, or
6
6
# (at your option) any later version.
7
 
#
 
7
 
8
8
# This program is distributed in the hope that it will be useful,
9
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11
11
# GNU General Public License for more details.
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
 
"""man.py - create man page from built-in brz help and static text
 
17
"""man.py - create man page from built-in bzr help and static text
18
18
 
19
19
TODO:
20
 
  * use usage information instead of simple "brz foo" in COMMAND OVERVIEW
 
20
  * use usage information instead of simple "bzr foo" in COMMAND OVERVIEW
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
 
 
30
 
import breezy
31
 
import breezy.help
32
 
import breezy.help_topics
33
 
import breezy.commands
34
 
from breezy.doc_generate import get_autodoc_datetime
35
 
 
36
 
from breezy.plugin import load_plugins
37
 
load_plugins()
 
27
import time
 
28
 
 
29
import bzrlib
 
30
import bzrlib.help
 
31
import bzrlib.commands
38
32
 
39
33
 
40
34
def get_filename(options):
41
35
    """Provides name of manpage"""
42
 
    return "%s.1" % (options.brz_name)
 
36
    return "%s.1" % (options.bzr_name)
43
37
 
44
38
 
45
39
def infogen(options, outfile):
46
40
    """Assembles a man page"""
47
 
    d = get_autodoc_datetime()
 
41
    t = time.time()
 
42
    tt = time.gmtime(t)
48
43
    params = \
49
 
        {"brzcmd": options.brz_name,
50
 
         "datestamp": d.strftime("%Y-%m-%d"),
51
 
         "timestamp": d.strftime("%Y-%m-%d %H:%M:%S +0000"),
52
 
         "version": breezy.__version__,
53
 
         }
 
44
           { "bzrcmd": options.bzr_name,
 
45
             "datestamp": time.strftime("%Y-%m-%d",tt),
 
46
             "timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
 
47
             "version": bzrlib.__version__,
 
48
             }
54
49
    outfile.write(man_preamble % params)
55
50
    outfile.write(man_escape(man_head % params))
56
51
    outfile.write(man_escape(getcommand_list(params)))
57
52
    outfile.write(man_escape(getcommand_help(params)))
58
 
    outfile.write("".join(environment_variables()))
59
53
    outfile.write(man_escape(man_foot % params))
60
54
 
61
55
 
62
56
def man_escape(string):
63
57
    """Escapes strings for man page compatibility"""
64
 
    result = string.replace("\\", "\\\\")
65
 
    result = result.replace("`", "\\'")
66
 
    result = result.replace("'", "\\*(Aq")
67
 
    result = result.replace("-", "\\-")
 
58
    result = string.replace("\\","\\\\")
 
59
    result = result.replace("`","\\`")
 
60
    result = result.replace("'","\\'")
 
61
    result = result.replace("-","\\-")
68
62
    return result
69
63
 
70
64
 
71
65
def command_name_list():
72
 
    """Builds a list of command names from breezy"""
73
 
    command_names = breezy.commands.builtin_command_names()
74
 
    for cmdname in breezy.commands.plugin_command_names():
75
 
        cmd_object = breezy.commands.get_cmd_object(cmdname)
76
 
        if (PLUGINS_TO_DOCUMENT is None or
77
 
                cmd_object.plugin_name() in PLUGINS_TO_DOCUMENT):
78
 
            command_names.append(cmdname)
 
66
    """Builds a list of command names from bzrlib"""
 
67
    command_names = bzrlib.commands.builtin_command_names()
79
68
    command_names.sort()
80
69
    return command_names
81
70
 
82
71
 
83
 
def getcommand_list(params):
 
72
def getcommand_list (params):
84
73
    """Builds summary help for command names in manpage format"""
85
 
    brzcmd = params["brzcmd"]
 
74
    bzrcmd = params["bzrcmd"]
86
75
    output = '.SH "COMMAND OVERVIEW"\n'
87
76
    for cmd_name in command_name_list():
88
 
        cmd_object = breezy.commands.get_cmd_object(cmd_name)
 
77
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
89
78
        if cmd_object.hidden:
90
79
            continue
91
80
        cmd_help = cmd_object.help()
92
81
        if cmd_help:
93
82
            firstline = cmd_help.split('\n', 1)[0]
94
 
            usage = cmd_object._usage()
 
83
            usage = bzrlib.help.command_usage(cmd_object)
95
84
            tmp = '.TP\n.B "%s"\n%s\n' % (usage, firstline)
96
85
            output = output + tmp
97
86
        else:
98
 
            raise RuntimeError("Command '%s' has no help text" % (cmd_name))
 
87
            raise RuntimeError, "Command '%s' has no help text" % (cmd_name)
99
88
    return output
100
89
 
101
90
 
102
91
def getcommand_help(params):
103
 
    """Shows individual options for a brz command"""
104
 
    output = '.SH "COMMAND REFERENCE"\n'
105
 
    formatted = {}
 
92
    """Shows individual options for a bzr command"""
 
93
    output='.SH "COMMAND REFERENCE"\n'
106
94
    for cmd_name in command_name_list():
107
 
        cmd_object = breezy.commands.get_cmd_object(cmd_name)
 
95
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
108
96
        if cmd_object.hidden:
109
97
            continue
110
 
        formatted[cmd_name] = format_command(params, cmd_object)
111
 
        for alias in cmd_object.aliases:
112
 
            formatted[alias] = format_alias(params, alias, cmd_name)
113
 
    for cmd_name in sorted(formatted):
114
 
        output += formatted[cmd_name]
 
98
        output = output + format_command(params, cmd_object)
115
99
    return output
116
100
 
117
101
 
118
 
def format_command(params, cmd):
 
102
def format_command (params, cmd):
119
103
    """Provides long help for each public command"""
120
 
    subsection_header = '.SS "%s"\n' % (cmd._usage())
 
104
    subsection_header = '.SS "%s"\n' % (bzrlib.help.command_usage(cmd))
121
105
    doc = "%s\n" % (cmd.__doc__)
122
 
    doc = breezy.help_topics.help_as_plain_text(cmd.help())
123
 
 
124
 
    # A dot at the beginning of a line is interpreted as a macro.
125
 
    # Simply join lines that begin with a dot with the previous
126
 
    # line to work around this.
127
 
    doc = doc.replace("\n.", ".")
128
 
 
 
106
    docsplit = cmd.__doc__.split('\n')
 
107
    doc = '\n'.join([docsplit[0]] + [line[4:] for line in docsplit[1:]])
129
108
    option_str = ""
130
109
    options = cmd.options()
131
110
    if options:
132
111
        option_str = "\nOptions:\n"
133
112
        for option_name, option in sorted(options.items()):
134
 
            for name, short_name, argname, help in option.iter_switches():
135
 
                if option.is_hidden(name):
136
 
                    continue
137
 
                l = '    --' + name
138
 
                if argname is not None:
139
 
                    l += ' ' + argname
140
 
                if short_name:
141
 
                    l += ', -' + short_name
142
 
                l += (30 - len(l)) * ' ' + (help or '')
143
 
                wrapped = textwrap.fill(l, initial_indent='',
144
 
                                        subsequent_indent=30 * ' ',
145
 
                                        break_long_words=False,
146
 
                                        )
147
 
                option_str += wrapped + '\n'
148
 
 
149
 
    aliases_str = ""
150
 
    if cmd.aliases:
151
 
        if len(cmd.aliases) > 1:
152
 
            aliases_str += '\nAliases: '
153
 
        else:
154
 
            aliases_str += '\nAlias: '
155
 
        aliases_str += ', '.join(cmd.aliases)
156
 
        aliases_str += '\n'
157
 
 
158
 
    see_also_str = ""
159
 
    see_also = cmd.get_see_also()
160
 
    if see_also:
161
 
        see_also_str += '\nSee also: '
162
 
        see_also_str += ', '.join(see_also)
163
 
        see_also_str += '\n'
164
 
 
165
 
    return subsection_header + option_str + aliases_str + see_also_str + "\n" + doc + "\n"
166
 
 
167
 
 
168
 
def format_alias(params, alias, cmd_name):
169
 
    help = '.SS "brz %s"\n' % alias
170
 
    help += 'Alias for "%s", see "brz %s".\n' % (cmd_name, cmd_name)
171
 
    return help
172
 
 
173
 
 
174
 
def environment_variables():
175
 
    yield ".SH \"ENVIRONMENT\"\n"
176
 
 
177
 
    from breezy.help_topics import known_env_variables
178
 
    for k, desc in known_env_variables:
179
 
        yield ".TP\n"
180
 
        yield ".I \"%s\"\n" % k
181
 
        yield man_escape(desc) + "\n"
 
113
            l = '    --' + option_name
 
114
            if option.type is not None:
 
115
                l += ' ' + option.argname.upper()
 
116
            short_name = option.short_name()
 
117
            if short_name:
 
118
                assert len(short_name) == 1
 
119
                l += ', -' + short_name
 
120
            l += (30 - len(l)) * ' ' + option.help
 
121
            # TODO: Split help over multiple lines with
 
122
            # correct indenting and wrapping.
 
123
            wrapped = textwrap.fill(l, initial_indent='',
 
124
                                    subsequent_indent=30*' ')
 
125
            option_str = option_str + wrapped + '\n'       
 
126
    return subsection_header + option_str + "\n" + doc + "\n"
182
127
 
183
128
 
184
129
man_preamble = """\
185
 
.\\\"Man page for Breezy (%(brzcmd)s)
 
130
Man page for %(bzrcmd)s (bazaar-ng)
186
131
.\\\"
187
132
.\\\" Large parts of this file are autogenerated from the output of
188
 
.\\\"     \"%(brzcmd)s help commands\"
189
 
.\\\"     \"%(brzcmd)s help <cmd>\"
190
 
.\\\"
191
 
 
192
 
.ie \\n(.g .ds Aq \\(aq
193
 
.el .ds Aq '
 
133
.\\\"     \"%(bzrcmd)s help commands\"
 
134
.\\\"     \"%(bzrcmd)s help <cmd>\"
 
135
.\\\"
 
136
.\\\" Generation time: %(timestamp)s
 
137
.\\\"
194
138
"""
195
139
 
196
140
 
197
141
man_head = """\
198
 
.TH brz 1 "%(datestamp)s" "%(version)s" "Breezy"
 
142
.TH bzr 1 "%(datestamp)s" "%(version)s" "bazaar-ng"
199
143
.SH "NAME"
200
 
%(brzcmd)s - Breezy next-generation distributed version control
 
144
%(bzrcmd)s - bazaar-ng next-generation distributed version control
201
145
.SH "SYNOPSIS"
202
 
.B "%(brzcmd)s"
 
146
.B "%(bzrcmd)s"
203
147
.I "command"
204
148
[
205
149
.I "command_options"
206
150
]
207
151
.br
208
 
.B "%(brzcmd)s"
 
152
.B "%(bzrcmd)s"
209
153
.B "help"
210
154
.br
211
 
.B "%(brzcmd)s"
 
155
.B "%(bzrcmd)s"
212
156
.B "help"
213
157
.I "command"
214
158
.SH "DESCRIPTION"
215
 
 
216
 
Breezy (or %(brzcmd)s) is a distributed version control system that is powerful,
217
 
friendly, and scalable.  Breezy is a fork of the Bazaar version control system.
218
 
 
219
 
Breezy keeps track of changes to software source code (or similar information);
220
 
lets you explore who changed it, when, and why; merges concurrent changes; and
221
 
helps people work together in a team.
 
159
bazaar-ng (or
 
160
.B "%(bzrcmd)s"
 
161
) 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.
222
162
"""
223
163
 
224
164
man_foot = """\
 
165
.SH "ENVIRONMENT"
 
166
.TP
 
167
.I "BZRPATH"
 
168
Path where
 
169
.B "%(bzrcmd)s"
 
170
is to look for external command.
 
171
.TP
 
172
.I "BZREMAIL"
 
173
E-Mail address of the user. Overrides default user config.
 
174
.TP
 
175
.I "EMAIL"
 
176
E-Mail address of the user. Overriddes default user config.
225
177
.SH "FILES"
226
178
.TP
227
 
.I "~/.config/breezy/breezy.conf"
228
 
Contains the user's default configuration. The section
 
179
.I "~/.bazaar/bazaar.conf/"
 
180
Contains the default user config. Only one section, [DEFAULT] is allowed. A 
 
181
typical default config file may be similiar to:
 
182
.br
 
183
.br
229
184
.B [DEFAULT]
230
 
is used to define general configuration that will be applied everywhere.
231
 
The section
232
 
.B [ALIASES]
233
 
can be used to create command aliases for
234
 
commonly used options.
235
 
 
236
 
A typical config file might look something like:
237
 
 
238
 
.br
239
 
[DEFAULT]
240
 
.br
241
 
email=John Doe <jdoe@isp.com>
242
 
.br
243
 
[ALIASES]
244
 
.br
245
 
commit = commit --strict
246
 
.br
247
 
log10 = log --short -r -10..-1
 
185
.br
 
186
.B email=John Doe <jdoe@isp.com>
248
187
.SH "SEE ALSO"
249
 
.UR https://www.breezy-vcs.org/
250
 
.BR https://www.breezy-vcs.org/
 
188
.UR http://www.bazaar-vcs.org/
 
189
.BR http://www.bazaar-vcs.org/
251
190
"""
 
191