86
77
If output_dir is not None, topics are dumped into text files there
87
78
during processing, as well as being included in the return result.
80
file_per_topic = output_dir is not None
81
lines = [title, hdg_level1 * len(title), ""]
83
lines.extend([".. toctree::", " :maxdepth: 1", ""])
89
85
topics = sorted(registry.get_topics_for_section(section))
90
lines = [title, hdg_level1 * len(title), ""]
92
# docutils treats section heading as implicit link target.
93
# But in some cases topic and heading are different, e.g.:
95
# `bugs' vs. `Bug Trackers'
96
# `working-tree' vs. `Working Trees'
98
# So for building proper cross-reference between topic names
99
# and corresponding sections in document, we need provide
100
# simple glue in the form:
102
# .. _topic: `heading`_
105
86
for topic in topics:
106
87
help = registry.get_detail(topic)
107
heading,text = help.split("\n", 1)
108
lines.append(heading)
88
heading, text = help.split("\n", 1)
109
89
if not text.startswith(hdg_level2):
110
lines.append(hdg_level2 * len(heading))
113
# check that topic match heading
114
if topic != heading.lower():
115
links_glue.append((topic, heading))
116
# dump the text if requested
117
if output_dir is not None:
118
out_file = bzrlib.osutils.pathjoin(output_dir, topic + ".txt")
119
_dump_text(out_file, help)
121
# provide links glue for topics that don't match headings
122
lines.extend([".. _%s: `%s`_" % i for i in links_glue])
90
underline = hdg_level2 * len(heading)
91
help = "%s\n%s\n\n%s\n\n" % (heading, underline, text)
93
help = "%s\n%s\n\n" % (heading, text)
95
topic_id = _dump_text(output_dir, topic, help)
96
lines.append(" %s" % topic_id)
125
100
return "\n" + "\n".join(lines) + "\n"
128
def _dump_text(filename, text):
129
"""Dump text to filename."""
130
if not FILE_PER_TOPIC:
132
f = open(filename, "w")
137
103
def _get_commands_section(registry, title="Commands", hdg_level1="#",
104
hdg_level2="=", output_dir=None):
139
105
"""Build the commands reference section of the manual."""
106
file_per_topic = output_dir is not None
140
107
lines = [title, hdg_level1 * len(title), ""]
109
lines.extend([".. toctree::", " :maxdepth: 1", ""])
141
111
cmds = sorted(bzrlib.commands.builtin_command_names())
142
112
for cmd_name in cmds:
143
113
cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
144
114
if cmd_object.hidden:
146
116
heading = cmd_name
117
underline = hdg_level2 * len(heading)
147
118
text = cmd_object.get_help_text(plain=False, see_also_as_links=True)
148
lines.append(heading)
149
lines.append(hdg_level2 * len(heading))
119
help = "%s\n%s\n\n%s\n\n" % (heading, underline, text)
121
topic_id = _dump_text(output_dir, cmd_name, help)
122
lines.append(" %s" % topic_id)
152
126
return "\n" + "\n".join(lines) + "\n"
129
def _dump_text(output_dir, topic, text):
130
"""Dump text for a topic to a file."""
131
topic_id = "%s-%s" % (topic, "help")
132
filename = bzrlib.osutils.pathjoin(output_dir, topic_id + ".txt")
133
f = open(filename, "w")
added
removed
bzrlib/doc_generate/autodoc_rstx.py
