45
47
"timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
46
48
"version": bzrlib.__version__,
50
nominated_filename = getattr(options, 'filename', None)
51
if nominated_filename is None:
54
topic_dir = bzrlib.osutils.dirname(nominated_filename)
48
55
outfile.write(rstx_preamble % params)
49
56
outfile.write(rstx_head % params)
50
outfile.write(getcommand_list(params))
51
outfile.write(getcommand_help(params))
57
outfile.write(_get_body(params, topic_dir))
52
58
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.__doc__.split('\n')
108
doc = '\n'.join([' '*4 + docsplit[0]] + docsplit[1:])
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'
128
return subsection_header + option_str + "\n" + doc + "\n"
61
def _get_body(params, topic_dir):
62
"""Build the manual content."""
63
from bzrlib.help_topics import SECT_CONCEPT, SECT_LIST, SECT_PLUGIN
64
registry = bzrlib.help_topics.topic_registry
66
result.append(_get_section(registry, SECT_CONCEPT, "Concepts",
67
output_dir=topic_dir))
68
result.append(_get_section(registry, SECT_LIST, "Lists",
69
output_dir=topic_dir))
70
result.append(_get_commands_section(registry))
71
#result.append(_get_section(registry, SECT_PLUGIN, "Standard Plug-ins"))
72
return "\n".join(result)
75
def _get_section(registry, section, title, hdg_level1="#", hdg_level2="=",
77
"""Build the manual part from topics matching that section.
79
If output_dir is not None, topics are dumped into text files there
80
during processing, as well as being included in the return result.
82
topics = sorted(registry.get_topics_for_section(section))
83
lines = [title, hdg_level1 * len(title), ""]
85
# docutils treats section heading as implicit link target.
86
# But in some cases topic and heading are different, e.g.:
88
# `bugs' vs. `Bug Trackers'
89
# `working-tree' vs. `Working Trees'
91
# So for building proper cross-reference between topic names
92
# and corresponding sections in document, we need provide
93
# simple glue in the form:
95
# .. _topic: `heading`_
99
help = registry.get_detail(topic)
100
heading,text = help.split("\n", 1)
101
lines.append(heading)
102
if not text.startswith(hdg_level2):
103
lines.append(hdg_level2 * len(heading))
106
# check that topic match heading
107
if topic != heading.lower():
108
links_glue.append((topic, heading))
109
# dump the text if requested
110
if output_dir is not None:
111
out_file = bzrlib.osutils.pathjoin(output_dir, topic + ".txt")
112
_dump_text(out_file, help)
114
# provide links glue for topics that don't match headings
115
lines.extend([".. _%s: `%s`_" % i for i in links_glue])
118
return "\n" + "\n".join(lines) + "\n"
121
def _dump_text(filename, text):
122
"""Dump text to filename."""
123
f = open(filename, "w")
128
def _get_commands_section(registry, title="Commands", hdg_level1="#",
130
"""Build the commands reference section of the manual."""
131
lines = [title, hdg_level1 * len(title), ""]
132
cmds = sorted(bzrlib.commands.builtin_command_names())
133
for cmd_name in cmds:
134
cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
135
if cmd_object.hidden:
138
text = cmd_object.get_help_text(plain=False, see_also_as_links=True)
139
lines.append(heading)
140
lines.append(hdg_level2 * len(heading))
143
return "\n" + "\n".join(lines) + "\n"
134
rstx_preamble = """.. Large parts of this file are autogenerated from the output of
149
rstx_preamble = """.. This file is autogenerated from the output of
150
.. %(bzrcmd)s help topics
135
151
.. %(bzrcmd)s help commands
136
152
.. %(bzrcmd)s help <cmd>
138
154
.. Generation time: %(timestamp)s
140
=============================================
141
Man page for %(bzrcmd)s (bazaar-ng)
142
=============================================
160
#####################
161
Bazaar User Reference
162
#####################
164
:Version: %(version)s
165
:Generated: %(datestamp)s
167
.. contents:: :depth: 2
156
%(bzrcmd)s - bazaar-ng next-generation distributed version control
160
**%(bzrcmd)s** *command* [ *command_options* ]
164
**%(bzrcmd)s help** *command*
169
bazaar-ng (or **%(bzrcmd)s**) is a project of Canonical to develop
170
an open source distributed version control system that is powerful,
171
friendly, and scalable. Version control means a system
172
that keeps track of previous revisions of software source code
173
or similar information and helps people work on it in teams.
174
This manual is generated from Bazaar's online help. To use
175
the online help system, try the following commands.
177
Introduction including a list of commonly used commands::
181
List of topics and a summary of each::
185
List of commands and a summary of each::
189
More information about a particular topic or command::
191
bzr help topic-or-command-name
193
The following web sites provide further information on Bazaar:
195
:Home page: http://www.bazaar-vcs.org/
196
:Official docs: http://doc.bazaar-vcs.org/
197
:Launchpad: https://launchpad.net/bzr/
181
Path where **%(bzrcmd)s** is to look for external command.
184
E-Mail address of the user. Overrides default user config.
187
E-Mail address of the user. Overriddes default user config.
192
**On Linux**: ``~/.bazaar/bazaar.conf/``
194
**On Windows**: ``C:\\Documents and Settings\\username\\Application Data\\bazaar\\2.0\\bazaar.conf``
196
Contains the default user config. Only one section, ``[DEFAULT]`` is allowed.
197
A typical default config file may be similiar to::
200
email=John Doe <jdoe@isp.com>
205
http://www.bazaar-vcs.org/
added
removed
tools/doc_generate/autodoc_rstx.py
