~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to tools/doc_generate/autodoc_rstx.py

  • Committer: Ian Clatworthy
  • Date: 2007-08-13 14:33:10 UTC
  • mto: (2733.1.1 ianc-integration)
  • mto: This revision was merged to the branch mainline in revision 2734.
  • Revision ID: ian.clatworthy@internode.on.net-20070813143310-twhj4la0qnupvze8
Added Quick Start Summary

Show diffs side-by-side

added added

removed removed

Lines of Context:
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
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
28
29
import bzrlib.help
29
30
import bzrlib.help_topics
30
31
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)
54
49
    outfile.write(rstx_preamble % params)
55
50
    outfile.write(rstx_head % params)
56
 
    outfile.write(_get_body(params, topic_dir))
 
51
    outfile.write(_get_body(params))
57
52
    outfile.write(rstx_foot % params)
58
53
 
59
54
 
60
 
def _get_body(params, topic_dir):
 
55
def _get_body(params):
61
56
    """Build the manual content."""
62
57
    from bzrlib.help_topics import SECT_CONCEPT, SECT_LIST, SECT_PLUGIN
63
58
    registry = bzrlib.help_topics.topic_registry
64
59
    result = []
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))
 
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"))
70
64
    return "\n".join(result)
71
65
 
72
66
 
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
 
 
 
67
def _get_section(registry, section, title, hdg_level1="=", hdg_level2="-"):
 
68
    """Build the manual part from topics matching that section."""
85
69
    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
 
86
85
    for topic in topics:
87
86
        help = registry.get_detail(topic)
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)
 
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('')
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="=", output_dir=None):
105
 
    """Build the commands reference section of the manual."""
106
 
    file_per_topic = output_dir is not None
 
103
def _get_commands_section(registry, title="Commands", hdg_level1="=",
 
104
                          hdg_level2="-"):
 
105
    """Build the comands reference section of the manual."""
107
106
    lines = [title, hdg_level1 * len(title), ""]
108
 
    if file_per_topic:
109
 
        lines.extend([".. toctree::", "   :maxdepth: 1", ""])
110
 
 
111
107
    cmds = sorted(bzrlib.commands.builtin_command_names())
112
108
    for cmd_name in cmds:
113
109
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
114
110
        if cmd_object.hidden:
115
111
            continue
116
112
        heading = cmd_name
117
 
        underline = hdg_level2 * len(heading)
118
113
        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
 
 
 
114
        lines.append(heading)
 
115
        lines.append(hdg_level2 * len(heading))
 
116
        lines.append(text)
 
117
        lines.append('')
126
118
    return "\n" + "\n".join(lines) + "\n"
127
119
 
128
120
 
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
121
##
140
122
# TEMPLATES
141
123
 
150
132
 
151
133
 
152
134
rstx_head = """\
153
 
#####################
 
135
=====================
154
136
Bazaar User Reference
155
 
#####################
 
137
=====================
 
138
 
 
139
:Version:   %(version)s
 
140
:Generated: %(datestamp)s
 
141
 
 
142
.. contents::
 
143
 
 
144
-----
156
145
 
157
146
About This Manual
158
 
#################
 
147
=================
159
148
 
160
149
This manual is generated from Bazaar's online help. To use
161
150
the online help system, try the following commands.
178
167
 
179
168
The following web sites provide further information on Bazaar:
180
169
 
181
 
:Home page:                     http://bazaar.canonical.com/
182
 
:Official docs:                 http://doc.bazaar.canonical.com/
 
170
:Home page:                     http://www.bazaar-vcs.org/
 
171
:Official docs:                 http://doc.bazaar-vcs.org/
183
172
:Launchpad:                     https://launchpad.net/bzr/
184
173
"""
185
174