← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/doc_generate/autodoc_rstx.py

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2009-11-17 03:20:35 UTC
  • mfrom: (4792.4.3 456036)
  • Revision ID: pqm@pqm.ubuntu.com-20091117032035-s3sgtlixj1lrminn
(Gordon Tyler) Fix IndexError during 'bzr ignore /' (#456036)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/doc_generate/autodoc_rstx.py
14
14
# along with this program; if not, write to the Free Software
15
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16
16
 
17
 
"""Generate reStructuredText source for the User Reference Manual.
 
17
"""Generate ReStructuredText source for the User Reference Manual.
18
18
Loosely based on the manpage generator autodoc_man.py.
19
19
 
20
20
Written by the Bazaar community.
31
31
import bzrlib.osutils
32
32
 
33
33
 
 
34
# Set this to True to generate a file per topic.
 
35
# This probably ought to be an option. The files probably
 
36
# ought to be prefixed with their section name as well so
 
37
# there's zero risk of clashing with a standard sphinx
 
38
# topic (like search.html).
 
39
FILE_PER_TOPIC = False
 
40
 
 
41
 
34
42
def get_filename(options):
35
43
    """Provides name of manual"""
36
44
    return "%s_man.txt" % (options.bzr_name)
66
74
        output_dir=topic_dir))
67
75
    result.append(_get_section(registry, SECT_LIST, "Lists",
68
76
        output_dir=topic_dir))
69
 
    result.append(_get_commands_section(registry, output_dir=topic_dir))
 
77
    result.append(_get_commands_section(registry))
 
78
    #result.append(_get_section(registry, SECT_PLUGIN, "Standard Plug-ins"))
70
79
    return "\n".join(result)
71
80
 
72
81
 
77
86
    If output_dir is not None, topics are dumped into text files there
78
87
    during processing, as well as being included in the return result.
79
88
    """
80
 
    file_per_topic = output_dir is not None
81
 
    lines = [title, hdg_level1 * len(title), ""]
82
 
    if file_per_topic:
83
 
        lines.extend([".. toctree::", "   :maxdepth: 1", ""])
84
 
 
85
89
    topics = sorted(registry.get_topics_for_section(section))
 
90
    lines = [title, hdg_level1 * len(title), ""]
 
91
 
 
92
    # docutils treats section heading as implicit link target.
 
93
    # But in some cases topic and heading are different, e.g.:
 
94
    #
 
95
    # `bugs' vs. `Bug Trackers'
 
96
    # `working-tree' vs. `Working Trees'
 
97
    #
 
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:
 
101
    #
 
102
    # .. _topic: `heading`_
 
103
    links_glue = []
 
104
 
86
105
    for topic in topics:
87
106
        help = registry.get_detail(topic)
88
 
        heading, text = help.split("\n", 1)
 
107
        heading,text = help.split("\n", 1)
 
108
        lines.append(heading)
89
109
        if not text.startswith(hdg_level2):
90
 
            underline = hdg_level2 * len(heading)
91
 
            help = "%s\n%s\n\n%s\n\n" % (heading, underline, text)
92
 
        else:
93
 
            help = "%s\n%s\n\n" % (heading, text)
94
 
        if file_per_topic:
95
 
            topic_id = _dump_text(output_dir, topic, help)
96
 
            lines.append("   %s" % topic_id)
97
 
        else:
98
 
            lines.append(help)
 
110
            lines.append(hdg_level2 * len(heading))
 
111
        lines.append(text)
 
112
        lines.append('')
 
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)
 
120
 
 
121
    # provide links glue for topics that don't match headings
 
122
    lines.extend([".. _%s: `%s`_" % i for i in links_glue])
 
123
    lines.append('')
99
124
 
100
125
    return "\n" + "\n".join(lines) + "\n"
101
126
 
102
127
 
 
128
def _dump_text(filename, text):
 
129
    """Dump text to filename."""
 
130
    if not FILE_PER_TOPIC:
 
131
        return
 
132
    f =  open(filename, "w")
 
133
    f.writelines(text)
 
134
    f.close()
 
135
 
 
136
 
103
137
def _get_commands_section(registry, title="Commands", hdg_level1="#",
104
 
        hdg_level2="=", output_dir=None):
 
138
                          hdg_level2="="):
105
139
    """Build the commands reference section of the manual."""
106
 
    file_per_topic = output_dir is not None
107
140
    lines = [title, hdg_level1 * len(title), ""]
108
 
    if file_per_topic:
109
 
        lines.extend([".. toctree::", "   :maxdepth: 1", ""])
110
 
 
111
141
    cmds = sorted(bzrlib.commands.builtin_command_names())
112
142
    for cmd_name in cmds:
113
143
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
114
144
        if cmd_object.hidden:
115
145
            continue
116
146
        heading = cmd_name
117
 
        underline = hdg_level2 * len(heading)
118
147
        text = cmd_object.get_help_text(plain=False, see_also_as_links=True)
119
 
        help = "%s\n%s\n\n%s\n\n" % (heading, underline, text)
120
 
        if file_per_topic:
121
 
            topic_id = _dump_text(output_dir, cmd_name, help)
122
 
            lines.append("   %s" % topic_id)
123
 
        else:
124
 
            lines.append(help)
125
 
 
 
148
        lines.append(heading)
 
149
        lines.append(hdg_level2 * len(heading))
 
150
        lines.append(text)
 
151
        lines.append('')
126
152
    return "\n" + "\n".join(lines) + "\n"
127
153
 
128
154
 
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")
134
 
    f.writelines(text)
135
 
    f.close()
136
 
    return topic_id
137
 
 
138
 
 
139
155
##
140
156
# TEMPLATES
141
157
 
178
194
 
179
195
The following web sites provide further information on Bazaar:
180
196
 
181
 
:Home page:                     http://bazaar.canonical.com/
182
 
:Official docs:                 http://doc.bazaar.canonical.com/
 
197
:Home page:                     http://www.bazaar-vcs.org/
 
198
:Official docs:                 http://doc.bazaar-vcs.org/
183
199
:Launchpad:                     https://launchpad.net/bzr/
184
200
"""
185
201