← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to tools/doc_generate/autodoc_rstx.py

  • Committer: Mark Hammond
  • Date: 2008-08-10 11:16:39 UTC
  • mto: (3606.5.3 1.6)
  • mto: This revision was merged to the branch mainline in revision 3626.
  • Revision ID: mhammond@skippinet.com.au-20080810111639-9upz1wig1s8lvz62
install all files with 'restartreplace uninsrestartdelete' and close
tbzrcache at uninstall time.

Show diffs side-by-side

added added

removed removed

Lines of Context:
tools/doc_generate/autodoc_rstx.py
1
 
# Copyright (C) 2006-2007 Canonical Ltd
 
1
# Copyright 2006-2007 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
12
12
#
13
13
# You should have received a copy of the GNU General Public License
14
14
# along with this program; if not, write to the Free Software
15
 
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
15
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  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.
22
22
 
23
23
import os
24
24
import sys
 
25
import textwrap
25
26
import time
26
27
 
27
28
import bzrlib
66
67
        output_dir=topic_dir))
67
68
    result.append(_get_section(registry, SECT_LIST, "Lists",
68
69
        output_dir=topic_dir))
69
 
    result.append(_get_commands_section(registry, output_dir=topic_dir))
 
70
    result.append(_get_commands_section(registry))
 
71
    #result.append(_get_section(registry, SECT_PLUGIN, "Standard Plug-ins"))
70
72
    return "\n".join(result)
71
73
 
72
74
 
77
79
    If output_dir is not None, topics are dumped into text files there
78
80
    during processing, as well as being included in the return result.
79
81
    """
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
82
    topics = sorted(registry.get_topics_for_section(section))
 
83
    lines = [title, hdg_level1 * len(title), ""]
 
84
 
 
85
    # docutils treats section heading as implicit link target.
 
86
    # But in some cases topic and heading are different, e.g.:
 
87
    #
 
88
    # `bugs' vs. `Bug Trackers'
 
89
    # `working-tree' vs. `Working Trees'
 
90
    #
 
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:
 
94
    #
 
95
    # .. _topic: `heading`_
 
96
    links_glue = []
 
97
 
86
98
    for topic in topics:
87
99
        help = registry.get_detail(topic)
88
 
        heading, text = help.split("\n", 1)
 
100
        heading,text = help.split("\n", 1)
 
101
        lines.append(heading)
89
102
        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)
 
103
            lines.append(hdg_level2 * len(heading))
 
104
        lines.append(text)
 
105
        lines.append('')
 
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)
 
113
 
 
114
    # provide links glue for topics that don't match headings
 
115
    lines.extend([".. _%s: `%s`_" % i for i in links_glue])
 
116
    lines.append('')
99
117
 
100
118
    return "\n" + "\n".join(lines) + "\n"
101
119
 
102
120
 
 
121
def _dump_text(filename, text):
 
122
    """Dump text to filename."""
 
123
    f =  open(filename, "w")
 
124
    f.writelines(text)
 
125
    f.close()
 
126
 
 
127
 
103
128
def _get_commands_section(registry, title="Commands", hdg_level1="#",
104
 
        hdg_level2="=", output_dir=None):
 
129
                          hdg_level2="="):
105
130
    """Build the commands reference section of the manual."""
106
 
    file_per_topic = output_dir is not None
107
131
    lines = [title, hdg_level1 * len(title), ""]
108
 
    if file_per_topic:
109
 
        lines.extend([".. toctree::", "   :maxdepth: 1", ""])
110
 
 
111
132
    cmds = sorted(bzrlib.commands.builtin_command_names())
112
133
    for cmd_name in cmds:
113
134
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
114
135
        if cmd_object.hidden:
115
136
            continue
116
137
        heading = cmd_name
117
 
        underline = hdg_level2 * len(heading)
118
138
        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
 
 
 
139
        lines.append(heading)
 
140
        lines.append(hdg_level2 * len(heading))
 
141
        lines.append(text)
 
142
        lines.append('')
126
143
    return "\n" + "\n".join(lines) + "\n"
127
144
 
128
145
 
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
146
##
140
147
# TEMPLATES
141
148
 
154
161
Bazaar User Reference
155
162
#####################
156
163
 
 
164
:Version:   %(version)s
 
165
:Generated: %(datestamp)s
 
166
 
 
167
.. contents:: :depth: 2
 
168
 
 
169
-----
 
170
 
157
171
About This Manual
158
172
#################
159
173
 
178
192
 
179
193
The following web sites provide further information on Bazaar:
180
194
 
181
 
:Home page:                     http://bazaar.canonical.com/
182
 
:Official docs:                 http://doc.bazaar.canonical.com/
 
195
:Home page:                     http://www.bazaar-vcs.org/
 
196
:Official docs:                 http://doc.bazaar-vcs.org/
183
197
:Launchpad:                     https://launchpad.net/bzr/
184
198
"""
185
199