← 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: Aaron Bentley
  • Date: 2006-06-21 14:30:57 UTC
  • mfrom: (1801.1.1 bzr.dev)
  • mto: This revision was merged to the branch mainline in revision 1803.
  • Revision ID: abentley@panoramicfeedback.com-20060621143057-776e4b8d707e430e
Install benchmarks. (Jelmer Vernooij)

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
9
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11
11
# GNU General Public License for more details.
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))
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"
 
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 = bzrlib.help.command_usage(cmd_object)
 
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 = bzrlib.help.command_usage(cmd)
 
101
    subsection_header = """
 
102
%s
 
103
%s
 
104
::
 
105
""" % (usage, '-'*len(usage))
 
106
 
 
107
    docsplit = cmd.__doc__.split('\n')
 
108
    doc = '\n'.join([' '*4 + docsplit[0]] + docsplit[1:])
 
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
            l = '        --' + option_name
 
116
            if option.type is not None:
 
117
                l += ' ' + option.argname.upper()
 
118
            short_name = option.short_name()
 
119
            if short_name:
 
120
                assert len(short_name) == 1
 
121
                l += ', -' + short_name
 
122
            l += (30 - len(l)) * ' ' + option.help
 
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
    return subsection_header + option_str + "\n" + doc + "\n"
143
129
 
144
130
 
145
131
##
146
132
# TEMPLATES
147
133
 
148
 
rstx_preamble = """.. This file is autogenerated from the output of
149
 
..     %(bzrcmd)s help topics
 
134
rstx_preamble = """.. Large parts of this file are autogenerated from the output of
150
135
..     %(bzrcmd)s help commands
151
136
..     %(bzrcmd)s help <cmd>
152
137
..
153
138
.. Generation time: %(timestamp)s
154
139
 
 
140
=============================================
 
141
Man page for %(bzrcmd)s (bazaar-ng)
 
142
=============================================
 
143
 
 
144
:Date: %(datestamp)s
 
145
 
 
146
`Index <#id1>`_
 
147
 
 
148
-----
 
149
 
155
150
"""
156
151
 
157
152
 
158
153
rstx_head = """\
159
 
#####################
160
 
Bazaar User Reference
161
 
#####################
162
 
 
163
 
:Version:   %(version)s
164
 
:Generated: %(datestamp)s
165
 
 
166
 
.. contents:: :depth: 3
167
 
 
168
 
-----
169
 
 
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/
 
154
Name
 
155
====
 
156
%(bzrcmd)s - bazaar-ng next-generation distributed version control
 
157
 
 
158
Synopsis
 
159
========
 
160
**%(bzrcmd)s** *command* [ *command_options* ]
 
161
 
 
162
**%(bzrcmd)s help**
 
163
 
 
164
**%(bzrcmd)s help** *command*
 
165
 
 
166
 
 
167
Description
 
168
===========
 
169
bazaar-ng (or **%(bzrcmd)s**) is a project of Canonical to develop
 
170
an open source distributed version control system that is powerful,
 
171
friendly, and scalable. Version control means a system
 
172
that keeps track of previous revisions of software source code
 
173
or similar information and helps people work on it in teams.
197
174
"""
198
175
 
199
176
 
200
177
rstx_foot = """
 
178
Environment
 
179
===========
 
180
**BZRPATH**
 
181
                Path where **%(bzrcmd)s** is to look for external command.
 
182
 
 
183
**BZREMAIL**
 
184
                E-Mail address of the user. Overrides default user config.
 
185
 
 
186
**EMAIL**
 
187
                E-Mail address of the user. Overriddes default user config.
 
188
 
 
189
Files
 
190
=====
 
191
 
 
192
**On Linux**:  ``~/.bazaar/bazaar.conf/``
 
193
 
 
194
**On Windows**: ``C:\\Documents and Settings\\username\\Application Data\\bazaar\\2.0\\bazaar.conf``
 
195
 
 
196
Contains the default user config. Only one section, ``[DEFAULT]`` is allowed.
 
197
A typical default config file may be similiar to::
 
198
 
 
199
    [DEFAULT]
 
200
    email=John Doe <jdoe@isp.com>
 
201
 
 
202
 
 
203
See also
 
204
========
 
205
http://www.bazaar-vcs.org/
 
206
 
 
207
--------------------
 
208
 
 
209
.. Contents::
 
210
        **Index**
201
211
"""