← 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

(jameinel) Allow 'bzr serve' to interpret SIGHUP as a graceful shutdown.
 (bug #795025) (John A Meinel)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/doc_generate/autodoc_rstx.py
1
 
# Copyright 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
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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
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.
22
22
 
23
23
import os
24
24
import sys
25
 
import textwrap
26
25
import time
27
26
 
28
27
import bzrlib
67
66
        output_dir=topic_dir))
68
67
    result.append(_get_section(registry, SECT_LIST, "Lists",
69
68
        output_dir=topic_dir))
70
 
    result.append(_get_commands_section(registry))
71
 
    #result.append(_get_section(registry, SECT_PLUGIN, "Standard Plug-ins"))
 
69
    result.append(_get_commands_section(registry, output_dir=topic_dir))
72
70
    return "\n".join(result)
73
71
 
74
72
 
79
77
    If output_dir is not None, topics are dumped into text files there
80
78
    during processing, as well as being included in the return result.
81
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
 
82
85
    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
 
 
98
86
    for topic in topics:
99
87
        help = registry.get_detail(topic)
100
 
        heading,text = help.split("\n", 1)
101
 
        lines.append(heading)
 
88
        heading, text = help.split("\n", 1)
102
89
        if not text.startswith(hdg_level2):
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('')
 
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)
117
99
 
118
100
    return "\n" + "\n".join(lines) + "\n"
119
101
 
120
102
 
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
 
 
128
103
def _get_commands_section(registry, title="Commands", hdg_level1="#",
129
 
                          hdg_level2="="):
 
104
        hdg_level2="=", output_dir=None):
130
105
    """Build the commands reference section of the manual."""
 
106
    file_per_topic = output_dir is not None
131
107
    lines = [title, hdg_level1 * len(title), ""]
 
108
    if file_per_topic:
 
109
        lines.extend([".. toctree::", "   :maxdepth: 1", ""])
 
110
 
132
111
    cmds = sorted(bzrlib.commands.builtin_command_names())
133
112
    for cmd_name in cmds:
134
113
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
135
114
        if cmd_object.hidden:
136
115
            continue
137
116
        heading = cmd_name
 
117
        underline = hdg_level2 * len(heading)
138
118
        text = cmd_object.get_help_text(plain=False, see_also_as_links=True)
139
 
        lines.append(heading)
140
 
        lines.append(hdg_level2 * len(heading))
141
 
        lines.append(text)
142
 
        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
 
143
126
    return "\n" + "\n".join(lines) + "\n"
144
127
 
145
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
 
146
139
##
147
140
# TEMPLATES
148
141
 
161
154
Bazaar User Reference
162
155
#####################
163
156
 
164
 
:Version:   %(version)s
165
 
:Generated: %(datestamp)s
166
 
 
167
 
.. contents:: :depth: 2
168
 
 
169
 
-----
170
 
 
171
157
About This Manual
172
158
#################
173
159
 
192
178
 
193
179
The following web sites provide further information on Bazaar:
194
180
 
195
 
:Home page:                     http://www.bazaar-vcs.org/
196
 
:Official docs:                 http://doc.bazaar-vcs.org/
 
181
:Home page:                     http://bazaar.canonical.com/
 
182
:Official docs:                 http://doc.bazaar.canonical.com/
197
183
:Launchpad:                     https://launchpad.net/bzr/
198
184
"""
199
185