← 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: Vincent Ladeuil
  • Date: 2007-06-20 14:25:06 UTC
  • mfrom: (2540 +trunk)
  • mto: This revision was merged to the branch mainline in revision 2646.
  • Revision ID: v.ladeuil+lp@free.fr-20070620142506-txsb1v8538kpsafw
merge bzr.dev @ 2540

Show diffs side-by-side

added added

removed removed

Lines of Context:
tools/doc_generate/autodoc_rstx.py
1
 
# Copyright (C) 2006-2007 Canonical Ltd
 
1
# Copyright 2006 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
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.
 
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
21
21
"""
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
 
import bzrlib.help_topics
30
30
import bzrlib.commands
31
 
import bzrlib.osutils
32
31
 
33
32
 
34
33
def get_filename(options):
46
45
             "timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
47
46
             "version": bzrlib.__version__,
48
47
             }
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
48
    outfile.write(rstx_preamble % params)
55
49
    outfile.write(rstx_head % params)
56
 
    outfile.write(_get_body(params, topic_dir))
 
50
    outfile.write(getcommand_list(params))
 
51
    outfile.write(getcommand_help(params))
57
52
    outfile.write(rstx_foot % params)
58
53
 
59
54
 
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, output_dir=topic_dir))
70
 
    return "\n".join(result)
71
 
 
72
 
 
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
 
 
85
 
    topics = sorted(registry.get_topics_for_section(section))
86
 
    for topic in topics:
87
 
        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)
99
 
 
100
 
    return "\n" + "\n".join(lines) + "\n"
101
 
 
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
107
 
    lines = [title, hdg_level1 * len(title), ""]
108
 
    if file_per_topic:
109
 
        lines.extend([".. toctree::", "   :maxdepth: 1", ""])
110
 
 
111
 
    cmds = sorted(bzrlib.commands.builtin_command_names())
112
 
    for cmd_name in cmds:
113
 
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
114
 
        if cmd_object.hidden:
115
 
            continue
116
 
        heading = cmd_name
117
 
        underline = hdg_level2 * len(heading)
118
 
        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
 
 
126
 
    return "\n" + "\n".join(lines) + "\n"
127
 
 
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
 
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"
137
146
 
138
147
 
139
148
##
140
149
# TEMPLATES
141
150
 
142
 
rstx_preamble = """.. This file is autogenerated from the output of
143
 
..     %(bzrcmd)s help topics
 
151
rstx_preamble = """.. Large parts of this file are autogenerated from the output of
144
152
..     %(bzrcmd)s help commands
145
153
..     %(bzrcmd)s help <cmd>
146
154
..
147
155
.. Generation time: %(timestamp)s
148
156
 
 
157
=============================================
 
158
Man page for Bazaar (%(bzrcmd)s)
 
159
=============================================
 
160
 
 
161
:Date: %(datestamp)s
 
162
 
 
163
`Index <#id1>`_
 
164
 
 
165
-----
 
166
 
149
167
"""
150
168
 
151
169
 
152
170
rstx_head = """\
153
 
#####################
154
 
Bazaar User Reference
155
 
#####################
156
 
 
157
 
About This Manual
158
 
#################
159
 
 
160
 
This manual is generated from Bazaar's online help. To use
161
 
the online help system, try the following commands.
162
 
 
163
 
    Introduction including a list of commonly used commands::
164
 
 
165
 
        bzr help
166
 
 
167
 
    List of topics and a summary of each::
168
 
 
169
 
        bzr help topics
170
 
 
171
 
    List of commands and a summary of each::
172
 
 
173
 
        bzr help commands
174
 
 
175
 
    More information about a particular topic or command::
176
 
 
177
 
        bzr help topic-or-command-name
178
 
 
179
 
The following web sites provide further information on Bazaar:
180
 
 
181
 
:Home page:                     http://bazaar.canonical.com/
182
 
:Official docs:                 http://doc.bazaar.canonical.com/
183
 
:Launchpad:                     https://launchpad.net/bzr/
 
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.
184
191
"""
185
192
 
186
193
 
187
194
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**
188
249
"""