← 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

  • Committer: Martin Pool
  • Date: 2009-09-14 02:30:23 UTC
  • mto: This revision was merged to the branch mainline in revision 4693.
  • Revision ID: mbp@sourcefrog.net-20090914023023-ros0f3ndo04j3bww
https://launchpad.net/bugs/429151
Clearer docs about bzr help.  (Thanks to Naoki)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/doc_generate/autodoc_rstx.py
1
 
# Copyright (C) 2006-2010 Canonical Ltd
 
1
# Copyright (C) 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.
66
66
        output_dir=topic_dir))
67
67
    result.append(_get_section(registry, SECT_LIST, "Lists",
68
68
        output_dir=topic_dir))
69
 
    result.append(_get_commands_section(registry, output_dir=topic_dir))
 
69
    result.append(_get_commands_section(registry))
 
70
    #result.append(_get_section(registry, SECT_PLUGIN, "Standard Plug-ins"))
70
71
    return "\n".join(result)
71
72
 
72
73
 
77
78
    If output_dir is not None, topics are dumped into text files there
78
79
    during processing, as well as being included in the return result.
79
80
    """
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
81
    topics = sorted(registry.get_topics_for_section(section))
 
82
    lines = [title, hdg_level1 * len(title), ""]
 
83
 
 
84
    # docutils treats section heading as implicit link target.
 
85
    # But in some cases topic and heading are different, e.g.:
 
86
    #
 
87
    # `bugs' vs. `Bug Trackers'
 
88
    # `working-tree' vs. `Working Trees'
 
89
    #
 
90
    # So for building proper cross-reference between topic names
 
91
    # and corresponding sections in document, we need provide
 
92
    # simple glue in the form:
 
93
    #
 
94
    # .. _topic: `heading`_
 
95
    links_glue = []
 
96
 
86
97
    for topic in topics:
87
98
        help = registry.get_detail(topic)
88
 
        heading, text = help.split("\n", 1)
 
99
        heading,text = help.split("\n", 1)
 
100
        lines.append(heading)
89
101
        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)
 
102
            lines.append(hdg_level2 * len(heading))
 
103
        lines.append(text)
 
104
        lines.append('')
 
105
        # check that topic match heading
 
106
        if topic != heading.lower():
 
107
            links_glue.append((topic, heading))
 
108
        # dump the text if requested
 
109
        if output_dir is not None:
 
110
            out_file = bzrlib.osutils.pathjoin(output_dir, topic + ".txt")
 
111
            _dump_text(out_file, help)
 
112
 
 
113
    # provide links glue for topics that don't match headings
 
114
    lines.extend([".. _%s: `%s`_" % i for i in links_glue])
 
115
    lines.append('')
99
116
 
100
117
    return "\n" + "\n".join(lines) + "\n"
101
118
 
102
119
 
 
120
def _dump_text(filename, text):
 
121
    """Dump text to filename."""
 
122
    f =  open(filename, "w")
 
123
    f.writelines(text)
 
124
    f.close()
 
125
 
 
126
 
103
127
def _get_commands_section(registry, title="Commands", hdg_level1="#",
104
 
        hdg_level2="=", output_dir=None):
 
128
                          hdg_level2="="):
105
129
    """Build the commands reference section of the manual."""
106
 
    file_per_topic = output_dir is not None
107
130
    lines = [title, hdg_level1 * len(title), ""]
108
 
    if file_per_topic:
109
 
        lines.extend([".. toctree::", "   :maxdepth: 1", ""])
110
 
 
111
131
    cmds = sorted(bzrlib.commands.builtin_command_names())
112
132
    for cmd_name in cmds:
113
133
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
114
134
        if cmd_object.hidden:
115
135
            continue
116
136
        heading = cmd_name
117
 
        underline = hdg_level2 * len(heading)
118
137
        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
 
 
 
138
        lines.append(heading)
 
139
        lines.append(hdg_level2 * len(heading))
 
140
        lines.append(text)
 
141
        lines.append('')
126
142
    return "\n" + "\n".join(lines) + "\n"
127
143
 
128
144
 
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
145
##
140
146
# TEMPLATES
141
147
 
154
160
Bazaar User Reference
155
161
#####################
156
162
 
 
163
:Version:   %(version)s
 
164
:Generated: %(datestamp)s
 
165
 
 
166
.. contents:: :depth: 3
 
167
 
 
168
-----
 
169
 
157
170
About This Manual
158
171
#################
159
172
 
178
191
 
179
192
The following web sites provide further information on Bazaar:
180
193
 
181
 
:Home page:                     http://bazaar.canonical.com/
182
 
:Official docs:                 http://doc.bazaar.canonical.com/
 
194
:Home page:                     http://www.bazaar-vcs.org/
 
195
:Official docs:                 http://doc.bazaar-vcs.org/
183
196
:Launchpad:                     https://launchpad.net/bzr/
184
197
"""
185
198