← 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-08-14 12:08:08 UTC
  • mto: This revision was merged to the branch mainline in revision 4614.
  • Revision ID: mbp@sourcefrog.net-20090814120808-4gvx7fhg44z29cj3
Use platform(aliased=1)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/doc_generate/autodoc_rstx.py
1
 
# Copyright 2006 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
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
16
 
 
17
 
"""Generate ReStructuredText source for manual.
18
 
Based on manpage generator autodoc_man.py
19
 
 
20
 
Written by Alexander Belchenko
 
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
16
 
 
17
"""Generate ReStructuredText source for the User Reference Manual.
 
18
Loosely based on the manpage generator autodoc_man.py.
 
19
 
 
20
Written by the Bazaar community.
21
21
"""
22
22
 
23
23
import os
24
24
import sys
25
 
import textwrap
26
25
import time
27
26
 
28
27
import bzrlib
29
28
import bzrlib.help
 
29
import bzrlib.help_topics
30
30
import bzrlib.commands
 
31
import bzrlib.osutils
31
32
 
32
33
 
33
34
def get_filename(options):
45
46
             "timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
46
47
             "version": bzrlib.__version__,
47
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)
48
54
    outfile.write(rstx_preamble % params)
49
55
    outfile.write(rstx_head % params)
50
 
    outfile.write(getcommand_list(params))
51
 
    outfile.write(getcommand_help(params))
 
56
    outfile.write(_get_body(params, topic_dir))
52
57
    outfile.write(rstx_foot % params)
53
58
 
54
59
 
55
 
def command_name_list():
56
 
    """Builds a list of command names from bzrlib"""
57
 
    command_names = bzrlib.commands.builtin_command_names()
58
 
    command_names.sort()
59
 
    return command_names
60
 
 
61
 
 
62
 
def getcommand_list (params):
63
 
    """Builds summary help for command names in RSTX format"""
64
 
    bzrcmd = params["bzrcmd"]
65
 
    output = """
66
 
Command overview
67
 
================
68
 
"""
69
 
    for cmd_name in command_name_list():
70
 
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
71
 
        if cmd_object.hidden:
72
 
            continue
73
 
        cmd_help = cmd_object.help()
74
 
        if cmd_help:
75
 
            firstline = cmd_help.split('\n', 1)[0]
76
 
            usage = cmd_object._usage()
77
 
            tmp = '**%s**\n\t%s\n\n' % (usage, firstline)
78
 
            output = output + tmp
79
 
        else:
80
 
            raise RuntimeError, "Command '%s' has no help text" % (cmd_name)
81
 
    return output
82
 
 
83
 
 
84
 
def getcommand_help(params):
85
 
    """Shows individual options for a bzr command"""
86
 
    output="""
87
 
Command reference
88
 
=================
89
 
"""
90
 
    for cmd_name in command_name_list():
91
 
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
92
 
        if cmd_object.hidden:
93
 
            continue
94
 
        output = output + format_command(params, cmd_object, cmd_name)
95
 
    return output
96
 
 
97
 
 
98
 
def format_command (params, cmd, name):
99
 
    """Provides long help for each public command"""
100
 
    usage = cmd._usage()
101
 
    subsection_header = """
102
 
%s
103
 
%s
104
 
::
105
 
""" % (usage, '-'*len(usage))
106
 
 
107
 
    docsplit = cmd.help().split('\n')
108
 
    doc = '\n'.join([' '*4+line for line in docsplit])
109
 
        
110
 
    option_str = ""
111
 
    options = cmd.options()
112
 
    if options:
113
 
        option_str = "\n    Options:\n"
114
 
        for option_name, option in sorted(options.items()):
115
 
            for name, short_name, argname, help in option.iter_switches():
116
 
                l = '    --' + name
117
 
                if argname is not None:
118
 
                    l += ' ' + argname
119
 
                if short_name:
120
 
                    assert len(short_name) == 1
121
 
                    l += ', -' + short_name
122
 
                l += (30 - len(l)) * ' ' + (help or '')
123
 
                # TODO: Split help over multiple lines with
124
 
                # correct indenting and wrapping.
125
 
                wrapped = textwrap.fill(l, initial_indent='',
126
 
                                        subsequent_indent=30*' ')
127
 
                option_str = option_str + wrapped + '\n'       
128
 
 
129
 
    aliases_str = ""
130
 
    if cmd.aliases:
131
 
        if len(cmd.aliases) > 1:
132
 
            aliases_str += '\n    Aliases: '
133
 
        else:
134
 
            aliases_str += '\n    Alias: '
135
 
        aliases_str += ', '.join(cmd.aliases)
136
 
        aliases_str += '\n'
137
 
 
138
 
    see_also_str = ""
139
 
    see_also = cmd.get_see_also()
140
 
    if see_also:
141
 
        see_also_str += '\n    See also: '
142
 
        see_also_str += ', '.join(see_also)
143
 
        see_also_str += '\n'
144
 
 
145
 
    return subsection_header + option_str + aliases_str + see_also_str + "\n" + doc + "\n"
 
60
def _get_body(params, topic_dir):
 
61
    """Build the manual content."""
 
62
    from bzrlib.help_topics import SECT_CONCEPT, SECT_LIST, SECT_PLUGIN
 
63
    registry = bzrlib.help_topics.topic_registry
 
64
    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))
 
70
    #result.append(_get_section(registry, SECT_PLUGIN, "Standard Plug-ins"))
 
71
    return "\n".join(result)
 
72
 
 
73
 
 
74
def _get_section(registry, section, title, hdg_level1="#", hdg_level2="=",
 
75
        output_dir=None):
 
76
    """Build the manual part from topics matching that section.
 
77
    
 
78
    If output_dir is not None, topics are dumped into text files there
 
79
    during processing, as well as being included in the return result.
 
80
    """
 
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
 
 
97
    for topic in topics:
 
98
        help = registry.get_detail(topic)
 
99
        heading,text = help.split("\n", 1)
 
100
        lines.append(heading)
 
101
        if not text.startswith(hdg_level2):
 
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('')
 
116
 
 
117
    return "\n" + "\n".join(lines) + "\n"
 
118
 
 
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
 
 
127
def _get_commands_section(registry, title="Commands", hdg_level1="#",
 
128
                          hdg_level2="="):
 
129
    """Build the commands reference section of the manual."""
 
130
    lines = [title, hdg_level1 * len(title), ""]
 
131
    cmds = sorted(bzrlib.commands.builtin_command_names())
 
132
    for cmd_name in cmds:
 
133
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
 
134
        if cmd_object.hidden:
 
135
            continue
 
136
        heading = cmd_name
 
137
        text = cmd_object.get_help_text(plain=False, see_also_as_links=True)
 
138
        lines.append(heading)
 
139
        lines.append(hdg_level2 * len(heading))
 
140
        lines.append(text)
 
141
        lines.append('')
 
142
    return "\n" + "\n".join(lines) + "\n"
146
143
 
147
144
 
148
145
##
149
146
# TEMPLATES
150
147
 
151
 
rstx_preamble = """.. Large parts of this file are autogenerated from the output of
 
148
rstx_preamble = """.. This file is autogenerated from the output of
 
149
..     %(bzrcmd)s help topics
152
150
..     %(bzrcmd)s help commands
153
151
..     %(bzrcmd)s help <cmd>
154
152
..
155
153
.. Generation time: %(timestamp)s
156
154
 
157
 
=============================================
158
 
Man page for Bazaar (%(bzrcmd)s)
159
 
=============================================
160
 
 
161
 
:Date: %(datestamp)s
162
 
 
163
 
`Index <#id1>`_
 
155
"""
 
156
 
 
157
 
 
158
rstx_head = """\
 
159
#####################
 
160
Bazaar User Reference
 
161
#####################
 
162
 
 
163
:Version:   %(version)s
 
164
:Generated: %(datestamp)s
 
165
 
 
166
.. contents:: :depth: 3
164
167
 
165
168
-----
166
169
 
167
 
"""
168
 
 
169
 
 
170
 
rstx_head = """\
171
 
Name
172
 
====
173
 
Bazaar (%(bzrcmd)s) - next-generation distributed version control
174
 
 
175
 
Synopsis
176
 
========
177
 
**%(bzrcmd)s** *command* [ *command_options* ]
178
 
 
179
 
**%(bzrcmd)s help**
180
 
 
181
 
**%(bzrcmd)s help** *command*
182
 
 
183
 
 
184
 
Description
185
 
===========
186
 
Bazaar (or **%(bzrcmd)s**) is a project of Canonical to develop
187
 
an open source distributed version control system that is powerful,
188
 
friendly, and scalable. Version control means a system
189
 
that keeps track of previous revisions of software source code
190
 
or similar information and helps people work on it in teams.
 
170
About This Manual
 
171
#################
 
172
 
 
173
This manual is generated from Bazaar's online help. To use
 
174
the online help system, try the following commands.
 
175
 
 
176
    Introduction including a list of commonly used commands::
 
177
 
 
178
        bzr help
 
179
 
 
180
    List of topics and a summary of each::
 
181
 
 
182
        bzr help topics
 
183
 
 
184
    List of commands and a summary of each::
 
185
 
 
186
        bzr help commands
 
187
 
 
188
    More information about a particular topic or command::
 
189
 
 
190
        bzr help topic-or-command-name
 
191
 
 
192
The following web sites provide further information on Bazaar:
 
193
 
 
194
:Home page:                     http://www.bazaar-vcs.org/
 
195
:Official docs:                 http://doc.bazaar-vcs.org/
 
196
:Launchpad:                     https://launchpad.net/bzr/
191
197
"""
192
198
 
193
199
 
194
200
rstx_foot = """
195
 
Environment
196
 
===========
197
 
**BZRPATH**
198
 
                Path where **%(bzrcmd)s** is to look for shell plugin external commands.
199
 
 
200
 
**BZR_EMAIL**
201
 
                E-Mail address of the user. Overrides default user config.
202
 
 
203
 
**EMAIL**
204
 
                E-Mail address of the user. Overrides default user config.
205
 
 
206
 
**BZR_EDITOR**
207
 
                Editor for editing commit messages
208
 
 
209
 
**EDITOR**
210
 
                Editor for editing commit messages
211
 
 
212
 
**BZR_PLUGIN_PATH**
213
 
                Paths where bzr should look for plugins
214
 
 
215
 
**BZR_HOME**
216
 
                Home directory for bzr
217
 
 
218
 
 
219
 
Files
220
 
=====
221
 
 
222
 
**On Linux**:  ``~/.bazaar/bazaar.conf``
223
 
 
224
 
**On Windows**: ``C:\\Documents and Settings\\username\\Application Data\\bazaar\\2.0\\bazaar.conf``
225
 
 
226
 
Contains the user's default configuration. The section ``[DEFAULT]`` is
227
 
used to define general configuration that will be applied everywhere.
228
 
The section ``[ALIASES]`` can be used to create command aliases for
229
 
commonly used options.
230
 
 
231
 
A typical config file might look something like::
232
 
 
233
 
  [DEFAULT]
234
 
  email=John Doe <jdoe@isp.com>
235
 
 
236
 
  [ALIASES]
237
 
  commit = commit --strict
238
 
  log10 = log --short -r -10..-1
239
 
 
240
 
 
241
 
See also
242
 
========
243
 
http://www.bazaar-vcs.org/
244
 
 
245
 
--------------------
246
 
 
247
 
.. Contents::
248
 
    **Index**
249
201
"""