← 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

Merge bzr.dev and tree-file-ids-as-tuples.

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.
21
21
"""
22
22
 
23
 
import os
24
 
import sys
25
 
import textwrap
 
23
from __future__ import absolute_import
 
24
 
26
25
import time
27
26
 
28
27
import bzrlib
29
28
import bzrlib.help
30
29
import bzrlib.help_topics
31
30
import bzrlib.commands
 
31
import bzrlib.osutils
32
32
 
33
33
 
34
34
def get_filename(options):
46
46
             "timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
47
47
             "version": bzrlib.__version__,
48
48
             }
 
49
    nominated_filename = getattr(options, 'filename', None)
 
50
    if nominated_filename is None:
 
51
        topic_dir = None
 
52
    else:
 
53
        topic_dir = bzrlib.osutils.dirname(nominated_filename)
49
54
    outfile.write(rstx_preamble % params)
50
55
    outfile.write(rstx_head % params)
51
 
    outfile.write(_get_body(params))
 
56
    outfile.write(_get_body(params, topic_dir))
52
57
    outfile.write(rstx_foot % params)
53
58
 
54
59
 
55
 
def _get_body(params):
 
60
def _get_body(params, topic_dir):
56
61
    """Build the manual content."""
57
62
    from bzrlib.help_topics import SECT_CONCEPT, SECT_LIST, SECT_PLUGIN
58
63
    registry = bzrlib.help_topics.topic_registry
59
64
    result = []
60
 
    result.append(_get_section(registry, SECT_CONCEPT, "Concepts"))
61
 
    result.append(_get_section(registry, SECT_LIST, "Lists"))
62
 
    result.append(_get_commands_section(registry))
63
 
    #result.append(_get_section(registry, SECT_PLUGIN, "Core Plug-ins"))
 
65
    result.append(_get_section(registry, SECT_CONCEPT, "Concepts",
 
66
        output_dir=topic_dir))
 
67
    result.append(_get_section(registry, SECT_LIST, "Lists",
 
68
        output_dir=topic_dir))
 
69
    result.append(_get_commands_section(registry, output_dir=topic_dir))
64
70
    return "\n".join(result)
65
71
 
66
72
 
67
 
def _get_section(registry, section, title, hdg_level1="=", hdg_level2="-"):
68
 
    """Build the manual part from topics matching that section."""
 
73
def _get_section(registry, section, title, hdg_level1="#", hdg_level2="=",
 
74
        output_dir=None):
 
75
    """Build the manual part from topics matching that section.
 
76
    
 
77
    If output_dir is not None, topics are dumped into text files there
 
78
    during processing, as well as being included in the return result.
 
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
 
69
85
    topics = sorted(registry.get_topics_for_section(section))
70
 
    lines = [title, hdg_level1 * len(title), ""]
71
 
 
72
 
    # docutils treats section heading as implicit link target.
73
 
    # But in some cases topic and heading are different, e.g.:
74
 
    #
75
 
    # `bugs' vs. `Bug Trackers'
76
 
    # `working-tree' vs. `Working Trees'
77
 
    #
78
 
    # So for building proper cross-reference between topic names
79
 
    # and corresponding sections in document, we need provide
80
 
    # simple glue in the form:
81
 
    #
82
 
    # .. _topic: `heading`_
83
 
    links_glue = []
84
 
 
85
86
    for topic in topics:
86
87
        help = registry.get_detail(topic)
87
 
        heading,text = help.split("\n", 1)
88
 
        lines.append(heading)
89
 
        lines.append(hdg_level2 * len(heading))
90
 
        lines.append(text)
91
 
        lines.append('')
92
 
        # check that topic match heading
93
 
        if topic != heading.lower():
94
 
            links_glue.append((topic, heading))
95
 
 
96
 
    # provide links glue for topics that don't match headings
97
 
    lines.extend([".. _%s: `%s`_" % i for i in links_glue])
98
 
    lines.append('')
 
88
        heading, text = help.split("\n", 1)
 
89
        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)
99
99
 
100
100
    return "\n" + "\n".join(lines) + "\n"
101
101
 
102
102
 
103
 
def _get_commands_section(registry, title="Commands", hdg_level1="=",
104
 
                          hdg_level2="-"):
105
 
    """Build the comands reference section of the manual."""
 
103
def _get_commands_section(registry, title="Commands", hdg_level1="#",
 
104
        hdg_level2="=", output_dir=None):
 
105
    """Build the commands reference section of the manual."""
 
106
    file_per_topic = output_dir is not None
106
107
    lines = [title, hdg_level1 * len(title), ""]
 
108
    if file_per_topic:
 
109
        lines.extend([".. toctree::", "   :maxdepth: 1", ""])
 
110
 
107
111
    cmds = sorted(bzrlib.commands.builtin_command_names())
108
112
    for cmd_name in cmds:
109
113
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
110
114
        if cmd_object.hidden:
111
115
            continue
112
116
        heading = cmd_name
 
117
        underline = hdg_level2 * len(heading)
113
118
        text = cmd_object.get_help_text(plain=False, see_also_as_links=True)
114
 
        lines.append(heading)
115
 
        lines.append(hdg_level2 * len(heading))
116
 
        lines.append(text)
117
 
        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
 
118
126
    return "\n" + "\n".join(lines) + "\n"
119
127
 
120
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
 
121
139
##
122
140
# TEMPLATES
123
141
 
132
150
 
133
151
 
134
152
rstx_head = """\
135
 
=====================
 
153
#####################
136
154
Bazaar User Reference
137
 
=====================
138
 
 
139
 
:Version:   %(version)s
140
 
:Generated: %(datestamp)s
141
 
 
142
 
.. contents::
143
 
 
144
 
-----
 
155
#####################
145
156
 
146
157
About This Manual
147
 
=================
 
158
#################
148
159
 
149
160
This manual is generated from Bazaar's online help. To use
150
161
the online help system, try the following commands.
167
178
 
168
179
The following web sites provide further information on Bazaar:
169
180
 
170
 
:Home page:                     http://www.bazaar-vcs.org/
171
 
:Official docs:                 http://doc.bazaar-vcs.org/
 
181
:Home page:                     http://bazaar.canonical.com/
 
182
:Official docs:                 http://doc.bazaar.canonical.com/
172
183
:Launchpad:                     https://launchpad.net/bzr/
173
184
"""
174
185