← 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: Ian Clatworthy
  • Date: 2007-12-11 02:07:30 UTC
  • mto: (3119.1.1 ianc-integration)
  • mto: This revision was merged to the branch mainline in revision 3120.
  • Revision ID: ian.clatworthy@internode.on.net-20071211020730-sdj4kj794dw0628e
make help topics more discoverable

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
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)
 
87
        heading,text = help.split("\n", 1)
 
88
        lines.append(heading)
89
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)
 
90
            lines.append(hdg_level2 * len(heading))
 
91
        lines.append(text)
 
92
        lines.append('')
 
93
        # check that topic match heading
 
94
        if topic != heading.lower():
 
95
            links_glue.append((topic, heading))
 
96
 
 
97
    # provide links glue for topics that don't match headings
 
98
    lines.extend([".. _%s: `%s`_" % i for i in links_glue])
 
99
    lines.append('')
99
100
 
100
101
    return "\n" + "\n".join(lines) + "\n"
101
102
 
102
103
 
103
104
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
 
105
                          hdg_level2="="):
 
106
    """Build the comands reference section of the manual."""
107
107
    lines = [title, hdg_level1 * len(title), ""]
108
 
    if file_per_topic:
109
 
        lines.extend([".. toctree::", "   :maxdepth: 1", ""])
110
 
 
111
108
    cmds = sorted(bzrlib.commands.builtin_command_names())
112
109
    for cmd_name in cmds:
113
110
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
114
111
        if cmd_object.hidden:
115
112
            continue
116
113
        heading = cmd_name
117
 
        underline = hdg_level2 * len(heading)
118
114
        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
 
 
 
115
        lines.append(heading)
 
116
        lines.append(hdg_level2 * len(heading))
 
117
        lines.append(text)
 
118
        lines.append('')
126
119
    return "\n" + "\n".join(lines) + "\n"
127
120
 
128
121
 
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
122
##
140
123
# TEMPLATES
141
124
 
154
137
Bazaar User Reference
155
138
#####################
156
139
 
 
140
:Version:   %(version)s
 
141
:Generated: %(datestamp)s
 
142
 
 
143
.. contents:: :depth: 2
 
144
 
 
145
-----
 
146
 
157
147
About This Manual
158
148
#################
159
149
 
178
168
 
179
169
The following web sites provide further information on Bazaar:
180
170
 
181
 
:Home page:                     http://bazaar.canonical.com/
182
 
:Official docs:                 http://doc.bazaar.canonical.com/
 
171
:Home page:                     http://www.bazaar-vcs.org/
 
172
:Official docs:                 http://doc.bazaar-vcs.org/
183
173
:Launchpad:                     https://launchpad.net/bzr/
184
174
"""
185
175