← 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: Canonical.com Patch Queue Manager
  • Date: 2009-04-01 01:34:50 UTC
  • mfrom: (4204.2.2 typos_200903)
  • Revision ID: pqm@pqm.ubuntu.com-20090401013450-7a9hdobj3p3f033c
(Matt Nordhoff) Fix a few typos in docstrings.

Show diffs side-by-side

added added

removed removed

Lines of Context:
tools/doc_generate/autodoc_rstx.py
1
 
# Copyright (C) 2006-2010 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
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.
21
21
"""
22
22
 
23
 
from __future__ import absolute_import
24
 
 
 
23
import os
 
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.write(text.encode('utf-8'))
135
 
    f.close()
136
 
    return topic_id
137
 
 
138
 
 
139
146
##
140
147
# TEMPLATES
141
148
 
144
151
..     %(bzrcmd)s help commands
145
152
..     %(bzrcmd)s help <cmd>
146
153
..
 
154
.. Generation time: %(timestamp)s
147
155
 
148
156
"""
149
157
 
153
161
Bazaar User Reference
154
162
#####################
155
163
 
 
164
:Version:   %(version)s
 
165
:Generated: %(datestamp)s
 
166
 
 
167
.. contents:: :depth: 2
 
168
 
 
169
-----
 
170
 
156
171
About This Manual
157
172
#################
158
173
 
177
192
 
178
193
The following web sites provide further information on Bazaar:
179
194
 
180
 
:Home page:                     http://bazaar.canonical.com/
181
 
:Official docs:                 http://doc.bazaar.canonical.com/
 
195
:Home page:                     http://www.bazaar-vcs.org/
 
196
:Official docs:                 http://doc.bazaar-vcs.org/
182
197
:Launchpad:                     https://launchpad.net/bzr/
183
198
"""
184
199