45
46
"timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
46
47
"version": bzrlib.__version__,
49
nominated_filename = getattr(options, 'filename', None)
50
if nominated_filename is None:
53
topic_dir = bzrlib.osutils.dirname(nominated_filename)
48
54
outfile.write(rstx_preamble % params)
49
55
outfile.write(rstx_head % params)
50
outfile.write(getcommand_list(params))
51
outfile.write(getcommand_help(params))
56
outfile.write(_get_body(params, topic_dir))
52
57
outfile.write(rstx_foot % params)
55
def command_name_list():
56
"""Builds a list of command names from bzrlib"""
57
command_names = bzrlib.commands.builtin_command_names()
62
def getcommand_list (params):
63
"""Builds summary help for command names in RSTX format"""
64
bzrcmd = params["bzrcmd"]
69
for cmd_name in command_name_list():
70
cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
73
cmd_help = cmd_object.help()
75
firstline = cmd_help.split('\n', 1)[0]
76
usage = bzrlib.help.command_usage(cmd_object)
77
tmp = '**%s**\n\t%s\n\n' % (usage, firstline)
80
raise RuntimeError, "Command '%s' has no help text" % (cmd_name)
84
def getcommand_help(params):
85
"""Shows individual options for a bzr command"""
90
for cmd_name in command_name_list():
91
cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
94
output = output + format_command(params, cmd_object, cmd_name)
98
def format_command (params, cmd, name):
99
"""Provides long help for each public command"""
100
usage = bzrlib.help.command_usage(cmd)
101
subsection_header = """
105
""" % (usage, '-'*len(usage))
107
docsplit = cmd.help().split('\n')
108
doc = '\n'.join([' '*4+line for line in docsplit])
111
options = cmd.options()
113
option_str = "\n Options:\n"
114
for option_name, option in sorted(options.items()):
115
l = ' --' + option_name
116
if option.type is not None:
117
l += ' ' + option.argname.upper()
118
short_name = option.short_name()
120
assert len(short_name) == 1
121
l += ', -' + short_name
122
l += (30 - len(l)) * ' ' + option.help
123
# TODO: Split help over multiple lines with
124
# correct indenting and wrapping.
125
wrapped = textwrap.fill(l, initial_indent='',
126
subsequent_indent=30*' ')
127
option_str = option_str + wrapped + '\n'
131
if len(cmd.aliases) > 1:
132
aliases_str += '\n Aliases: '
134
aliases_str += '\n Alias: '
135
aliases_str += ', '.join(cmd.aliases)
138
return subsection_header + option_str + aliases_str + "\n" + doc + "\n"
60
def _get_body(params, topic_dir):
61
"""Build the manual content."""
62
from bzrlib.help_topics import SECT_CONCEPT, SECT_LIST, SECT_PLUGIN
63
registry = bzrlib.help_topics.topic_registry
65
result.append(_get_section(registry, SECT_CONCEPT, "Concepts",
66
output_dir=topic_dir))
67
result.append(_get_section(registry, SECT_LIST, "Lists",
68
output_dir=topic_dir))
69
result.append(_get_commands_section(registry))
70
#result.append(_get_section(registry, SECT_PLUGIN, "Standard Plug-ins"))
71
return "\n".join(result)
74
def _get_section(registry, section, title, hdg_level1="#", hdg_level2="=",
76
"""Build the manual part from topics matching that section.
78
If output_dir is not None, topics are dumped into text files there
79
during processing, as well as being included in the return result.
81
topics = sorted(registry.get_topics_for_section(section))
82
lines = [title, hdg_level1 * len(title), ""]
84
# docutils treats section heading as implicit link target.
85
# But in some cases topic and heading are different, e.g.:
87
# `bugs' vs. `Bug Trackers'
88
# `working-tree' vs. `Working Trees'
90
# So for building proper cross-reference between topic names
91
# and corresponding sections in document, we need provide
92
# simple glue in the form:
94
# .. _topic: `heading`_
98
help = registry.get_detail(topic)
99
heading,text = help.split("\n", 1)
100
lines.append(heading)
101
if not text.startswith(hdg_level2):
102
lines.append(hdg_level2 * len(heading))
105
# check that topic match heading
106
if topic != heading.lower():
107
links_glue.append((topic, heading))
108
# dump the text if requested
109
if output_dir is not None:
110
out_file = bzrlib.osutils.pathjoin(output_dir, topic + ".txt")
111
_dump_text(out_file, help)
113
# provide links glue for topics that don't match headings
114
lines.extend([".. _%s: `%s`_" % i for i in links_glue])
117
return "\n" + "\n".join(lines) + "\n"
120
def _dump_text(filename, text):
121
"""Dump text to filename."""
122
f = open(filename, "w")
127
def _get_commands_section(registry, title="Commands", hdg_level1="#",
129
"""Build the commands reference section of the manual."""
130
lines = [title, hdg_level1 * len(title), ""]
131
cmds = sorted(bzrlib.commands.builtin_command_names())
132
for cmd_name in cmds:
133
cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
134
if cmd_object.hidden:
137
text = cmd_object.get_help_text(plain=False, see_also_as_links=True)
138
lines.append(heading)
139
lines.append(hdg_level2 * len(heading))
142
return "\n" + "\n".join(lines) + "\n"
144
rstx_preamble = """.. Large parts of this file are autogenerated from the output of
148
rstx_preamble = """.. This file is autogenerated from the output of
149
.. %(bzrcmd)s help topics
145
150
.. %(bzrcmd)s help commands
146
151
.. %(bzrcmd)s help <cmd>
148
153
.. Generation time: %(timestamp)s
150
=============================================
151
Man page for Bazaar (%(bzrcmd)s)
152
=============================================
159
#####################
160
Bazaar User Reference
161
#####################
163
:Version: %(version)s
164
:Generated: %(datestamp)s
166
.. contents:: :depth: 2
166
Bazaar (%(bzrcmd)s) - next-generation distributed version control
170
**%(bzrcmd)s** *command* [ *command_options* ]
174
**%(bzrcmd)s help** *command*
179
Bazaar (or **%(bzrcmd)s**) is a project of Canonical to develop
180
an open source distributed version control system that is powerful,
181
friendly, and scalable. Version control means a system
182
that keeps track of previous revisions of software source code
183
or similar information and helps people work on it in teams.
173
This manual is generated from Bazaar's online help. To use
174
the online help system, try the following commands.
176
Introduction including a list of commonly used commands::
180
List of topics and a summary of each::
184
List of commands and a summary of each::
188
More information about a particular topic or command::
190
bzr help topic-or-command-name
192
The following web sites provide further information on Bazaar:
194
:Home page: http://www.bazaar-vcs.org/
195
:Official docs: http://doc.bazaar-vcs.org/
196
:Launchpad: https://launchpad.net/bzr/
191
Path where **%(bzrcmd)s** is to look for external command.
194
E-Mail address of the user. Overrides default user config.
197
E-Mail address of the user. Overriddes default user config.
200
Editor for editing commit messages
203
Editor for editing commit messages
206
Paths where bzr should look for plugins
209
Home directory for bzr
215
**On Linux**: ``~/.bazaar/bazaar.conf``
217
**On Windows**: ``C:\\Documents and Settings\\username\\Application Data\\bazaar\\2.0\\bazaar.conf``
219
Contains the users default configuration. The section ``[DEFAULT]`` is
220
used to define general configuration that will be applied everywhere.
221
The section ``[ALIASES]`` can be used to create command aliases for
222
commonly used options.
224
A typical config file might look something like::
227
email=John Doe <jdoe@isp.com>
230
commit = commit --strict
231
log10 = log --short -r -10..-1
236
http://www.bazaar-vcs.org/
added
removed
bzrlib/doc_generate/autodoc_rstx.py
