← 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: Martin Pool
  • Date: 2006-04-20 02:51:31 UTC
  • mto: This revision was merged to the branch mainline in revision 1676.
  • Revision ID: mbp@sourcefrog.net-20060420025131-c042b29593764349
[patch] html manual generator (Alexander Belchenko)

Show diffs side-by-side

added added

removed removed

Lines of Context:
tools/doc_generate/autodoc_rstx.py
 
1
# Copyright 2006 Canonical Ltd.
 
2
#
 
3
# This program is free software; you can redistribute it and/or modify
 
4
# it under the terms of the GNU General Public License as published by
 
5
# the Free Software Foundation; either version 2 of the License, or
 
6
# (at your option) any later version.
 
7
#
 
8
# This program is distributed in the hope that it will be useful,
 
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
 
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
11
# GNU General Public License for more details.
 
12
 
 
13
# You should have received a copy of the GNU General Public License
 
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
 
21
"""
 
22
 
 
23
import os
 
24
import sys
 
25
import textwrap
 
26
import time
 
27
 
 
28
import bzrlib
 
29
import bzrlib.help
 
30
import bzrlib.commands
 
31
 
 
32
 
 
33
def get_filename(options):
 
34
    """Provides name of manual"""
 
35
    return "%s_man.txt" % (options.bzr_name)
 
36
 
 
37
 
 
38
def infogen(options, outfile):
 
39
    """Create manual in RSTX format"""
 
40
    t = time.time()
 
41
    tt = time.gmtime(t)
 
42
    params = \
 
43
           { "bzrcmd": options.bzr_name,
 
44
             "datestamp": time.strftime("%Y-%m-%d",tt),
 
45
             "timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
 
46
             "version": bzrlib.__version__,
 
47
             }
 
48
    outfile.write(rstx_preamble % params)
 
49
    outfile.write(rstx_head % params)
 
50
    outfile.write(getcommand_list(params))
 
51
    outfile.write(getcommand_help(params))
 
52
    outfile.write(rstx_foot % params)
 
53
 
 
54
 
 
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"
 
129
 
 
130
 
 
131
##
 
132
# TEMPLATES
 
133
 
 
134
rstx_preamble = """.. Large parts of this file are autogenerated from the output of
 
135
..     %(bzrcmd)s help commands
 
136
..     %(bzrcmd)s help <cmd>
 
137
..
 
138
.. Generation time: %(timestamp)s
 
139
 
 
140
=============================================
 
141
Man page for %(bzrcmd)s (bazaar-ng)
 
142
=============================================
 
143
 
 
144
:Date: %(datestamp)s
 
145
 
 
146
`Index <#id1>`_
 
147
 
 
148
-----
 
149
 
 
150
"""
 
151
 
 
152
 
 
153
rstx_head = """\
 
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.
 
174
 
 
175
Warning
 
176
-------
 
177
bazaar-ng is at an early stage of development,
 
178
and the design is still changing from week to week.
 
179
This man page here may be inconsistent with itself,
 
180
with other documentation or with the code,
 
181
and sometimes refer to features that are planned but not yet written.
 
182
Comments are still very welcome; please send them
 
183
to bazaar-ng@lists.canonical.com.
 
184
 
 
185
"""
 
186
 
 
187
 
 
188
rstx_foot = """
 
189
Environment
 
190
===========
 
191
**BZRPATH**
 
192
                Path where **%(bzrcmd)s** is to look for external command.
 
193
 
 
194
**BZREMAIL**
 
195
                E-Mail address of the user. Overrides default user config.
 
196
 
 
197
**EMAIL**
 
198
                E-Mail address of the user. Overriddes default user config.
 
199
 
 
200
Files
 
201
=====
 
202
 
 
203
**On Linux**:  ``~/.bazaar/bazaar.conf/``
 
204
 
 
205
**On Windows**: ``C:\\Documents and Settings\\username\\Application Data\\bazaar\\2.0\\bazaar.conf``
 
206
 
 
207
Contains the default user config. Only one section, ``[DEFAULT]`` is allowed.
 
208
A typical default config file may be similiar to::
 
209
 
 
210
    [DEFAULT]
 
211
    email=John Doe <jdoe@isp.com>
 
212
 
 
213
 
 
214
See also
 
215
========
 
216
http://bazaar.canonical.com/, http://www.bazaar-vcs.org/
 
217
 
 
218
--------------------
 
219
 
 
220
.. Contents::
 
221
        **Index**
 
222
"""