← 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: John Arbash Meinel
  • Date: 2010-07-13 07:44:02 UTC
  • mto: This revision was merged to the branch mainline in revision 5342.
  • Revision ID: john@arbash-meinel.com-20100713074402-wp3oh7cyx76fkvmm
Bump trunk to 2.3-dev1

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/doc_generate/autodoc_rstx.py
1
 
# Copyright (C) 2006-2007 Canonical Ltd
 
1
# Copyright (C) 2006-2010 Canonical Ltd
2
2
#
3
3
# This program is free software; you can redistribute it and/or modify
4
4
# it under the terms of the GNU General Public License as published by
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.
66
66
        output_dir=topic_dir))
67
67
    result.append(_get_section(registry, SECT_LIST, "Lists",
68
68
        output_dir=topic_dir))
69
 
    result.append(_get_commands_section(registry))
70
 
    #result.append(_get_section(registry, SECT_PLUGIN, "Standard Plug-ins"))
 
69
    result.append(_get_commands_section(registry, output_dir=topic_dir))
71
70
    return "\n".join(result)
72
71
 
73
72
 
78
77
    If output_dir is not None, topics are dumped into text files there
79
78
    during processing, as well as being included in the return result.
80
79
    """
 
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
 
81
85
    topics = sorted(registry.get_topics_for_section(section))
82
 
    lines = [title, hdg_level1 * len(title), ""]
83
 
 
84
 
    # docutils treats section heading as implicit link target.
85
 
    # But in some cases topic and heading are different, e.g.:
86
 
    #
87
 
    # `bugs' vs. `Bug Trackers'
88
 
    # `working-tree' vs. `Working Trees'
89
 
    #
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:
93
 
    #
94
 
    # .. _topic: `heading`_
95
 
    links_glue = []
96
 
 
97
86
    for topic in topics:
98
87
        help = registry.get_detail(topic)
99
 
        heading,text = help.split("\n", 1)
100
 
        lines.append(heading)
 
88
        heading, text = help.split("\n", 1)
101
89
        if not text.startswith(hdg_level2):
102
 
            lines.append(hdg_level2 * len(heading))
103
 
        lines.append(text)
104
 
        lines.append('')
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)
112
 
 
113
 
    # provide links glue for topics that don't match headings
114
 
    lines.extend([".. _%s: `%s`_" % i for i in links_glue])
115
 
    lines.append('')
 
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)
116
99
 
117
100
    return "\n" + "\n".join(lines) + "\n"
118
101
 
119
102
 
120
 
def _dump_text(filename, text):
121
 
    """Dump text to filename."""
122
 
    f =  open(filename, "w")
123
 
    f.writelines(text)
124
 
    f.close()
125
 
 
126
 
 
127
103
def _get_commands_section(registry, title="Commands", hdg_level1="#",
128
 
                          hdg_level2="="):
 
104
        hdg_level2="=", output_dir=None):
129
105
    """Build the commands reference section of the manual."""
 
106
    file_per_topic = output_dir is not None
130
107
    lines = [title, hdg_level1 * len(title), ""]
 
108
    if file_per_topic:
 
109
        lines.extend([".. toctree::", "   :maxdepth: 1", ""])
 
110
 
131
111
    cmds = sorted(bzrlib.commands.builtin_command_names())
132
112
    for cmd_name in cmds:
133
113
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
134
114
        if cmd_object.hidden:
135
115
            continue
136
116
        heading = cmd_name
 
117
        underline = hdg_level2 * len(heading)
137
118
        text = cmd_object.get_help_text(plain=False, see_also_as_links=True)
138
 
        lines.append(heading)
139
 
        lines.append(hdg_level2 * len(heading))
140
 
        lines.append(text)
141
 
        lines.append('')
 
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
 
142
126
    return "\n" + "\n".join(lines) + "\n"
143
127
 
144
128
 
 
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
 
145
139
##
146
140
# TEMPLATES
147
141
 
160
154
Bazaar User Reference
161
155
#####################
162
156
 
163
 
:Version:   %(version)s
164
 
:Generated: %(datestamp)s
165
 
 
166
 
.. contents:: :depth: 2
167
 
 
168
 
-----
169
 
 
170
157
About This Manual
171
158
#################
172
159
 
191
178
 
192
179
The following web sites provide further information on Bazaar:
193
180
 
194
 
:Home page:                     http://www.bazaar-vcs.org/
195
 
:Official docs:                 http://doc.bazaar-vcs.org/
 
181
:Home page:                     http://bazaar.canonical.com/
 
182
:Official docs:                 http://doc.bazaar.canonical.com/
196
183
:Launchpad:                     https://launchpad.net/bzr/
197
184
"""
198
185