/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 breezy/doc_generate/autodoc_man.py

  • Committer: Jelmer Vernooij
  • Date: 2018-05-19 13:16:11 UTC
  • mto: (6968.4.3 git-archive)
  • mto: This revision was merged to the branch mainline in revision 6972.
  • Revision ID: jelmer@jelmer.uk-20180519131611-l9h9ud41j7qg1m03
Move tar/zip to breezy.archive.

Show diffs side-by-side

added added

removed removed

Lines of Context:
breezy/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 brz help and static text
 
18
 
 
19
TODO:
 
20
  * use usage information instead of simple "brz foo" in COMMAND OVERVIEW
 
21
  * add command aliases
 
22
"""
 
23
 
 
24
from __future__ import absolute_import
 
25
 
 
26
PLUGINS_TO_DOCUMENT = ["launchpad"]
 
27
 
 
28
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()
 
38
 
 
39
 
 
40
def get_filename(options):
 
41
    """Provides name of manpage"""
 
42
    return "%s.1" % (options.brz_name)
 
43
 
 
44
 
 
45
def infogen(options, outfile):
 
46
    """Assembles a man page"""
 
47
    d = get_autodoc_datetime()
 
48
    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
             }
 
54
    outfile.write(man_preamble % params)
 
55
    outfile.write(man_escape(man_head % params))
 
56
    outfile.write(man_escape(getcommand_list(params)))
 
57
    outfile.write(man_escape(getcommand_help(params)))
 
58
    outfile.write("".join(environment_variables()))
 
59
    outfile.write(man_escape(man_foot % params))
 
60
 
 
61
 
 
62
def man_escape(string):
 
63
    """Escapes strings for man page compatibility"""
 
64
    result = string.replace("\\", "\\\\")
 
65
    result = result.replace("`", "\\'")
 
66
    result = result.replace("'", "\\*(Aq")
 
67
    result = result.replace("-", "\\-")
 
68
    return result
 
69
 
 
70
 
 
71
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)
 
79
    command_names.sort()
 
80
    return command_names
 
81
 
 
82
 
 
83
def getcommand_list (params):
 
84
    """Builds summary help for command names in manpage format"""
 
85
    brzcmd = params["brzcmd"]
 
86
    output = '.SH "COMMAND OVERVIEW"\n'
 
87
    for cmd_name in command_name_list():
 
88
        cmd_object = breezy.commands.get_cmd_object(cmd_name)
 
89
        if cmd_object.hidden:
 
90
            continue
 
91
        cmd_help = cmd_object.help()
 
92
        if cmd_help:
 
93
            firstline = cmd_help.split('\n', 1)[0]
 
94
            usage = cmd_object._usage()
 
95
            tmp = '.TP\n.B "%s"\n%s\n' % (usage, firstline)
 
96
            output = output + tmp
 
97
        else:
 
98
            raise RuntimeError("Command '%s' has no help text" % (cmd_name))
 
99
    return output
 
100
 
 
101
 
 
102
def getcommand_help(params):
 
103
    """Shows individual options for a brz command"""
 
104
    output='.SH "COMMAND REFERENCE"\n'
 
105
    formatted = {}
 
106
    for cmd_name in command_name_list():
 
107
        cmd_object = breezy.commands.get_cmd_object(cmd_name)
 
108
        if cmd_object.hidden:
 
109
            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]
 
115
    return output
 
116
 
 
117
 
 
118
def format_command(params, cmd):
 
119
    """Provides long help for each public command"""
 
120
    subsection_header = '.SS "%s"\n' % (cmd._usage())
 
121
    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
 
 
129
    option_str = ""
 
130
    options = cmd.options()
 
131
    if options:
 
132
        option_str = "\nOptions:\n"
 
133
        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"
 
182
 
 
183
 
 
184
man_preamble = """\
 
185
.\\\"Man page for Breezy (%(brzcmd)s)
 
186
.\\\"
 
187
.\\\" 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 '
 
194
"""
 
195
 
 
196
 
 
197
man_head = """\
 
198
.TH brz 1 "%(datestamp)s" "%(version)s" "Breezy"
 
199
.SH "NAME"
 
200
%(brzcmd)s - Breezy next-generation distributed version control
 
201
.SH "SYNOPSIS"
 
202
.B "%(brzcmd)s"
 
203
.I "command"
 
204
[
 
205
.I "command_options"
 
206
]
 
207
.br
 
208
.B "%(brzcmd)s"
 
209
.B "help"
 
210
.br
 
211
.B "%(brzcmd)s"
 
212
.B "help"
 
213
.I "command"
 
214
.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.
 
222
"""
 
223
 
 
224
man_foot = """\
 
225
.SH "FILES"
 
226
.TP
 
227
.I "~/.config/breezy/breezy.conf"
 
228
Contains the user's default configuration. The section
 
229
.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
 
248
.SH "SEE ALSO"
 
249
.UR https://www.breezy-vcs.org/
 
250
.BR https://www.breezy-vcs.org/
 
251
"""
 
252