← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzr_man.py

Start implementing general doc generation plan:
  * describe the plan
  * steal some code from bzrlib.help to extract command help
  * use subsections for each bzr command
  * add COMMAND OVERVIEW section
  * add USAGE section with a few common use cases
  * remove copyright marks as I am going to sign over copyright to Canonical

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzr_man.py
1
1
#!/usr/bin/python
2
2
 
3
 
# Marked portions Copyright (C) 2005 by Hans Ulrich Niedermann
4
 
# Unmarked portions (C) 2005 Canonical Ltd.
 
3
# Copyright 2005 Canonical Ltd.
5
4
 
6
5
# This program is free software; you can redistribute it and/or modify
7
6
# it under the terms of the GNU General Public License as published by
17
16
# along with this program; if not, write to the Free Software
18
17
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
19
18
 
 
19
"""bzr_man.py - create man page from built-in bzr help and static text
 
20
 
 
21
Plan (devised by jblack and ndim 2005-12-10):
 
22
  * one bzr_gen_stuff.py script in top level dir right beside bzr
 
23
  * one gen_stuff_extras/ directory
 
24
  * several generator scripts like
 
25
          gen_stuff_extras/gen_man_page.py
 
26
                           gen_docbook_xml.py
 
27
                           gen_html.py
 
28
                           gen_bash_completion.py
 
29
                           gen_zsh_completion.py
 
30
  * scripts are called by running "bzr_gen_stuff.py --man-page" or
 
31
    "--bash-completion"
 
32
  * one test case which iterates through all gen_*.py scripts and
 
33
    tries to generate all the file types, checking that all generators
 
34
    work
 
35
  * those generator scripts walk through the command and option data
 
36
    structures to extract the required information
 
37
  * the actual names are just prototypes and subject to change
 
38
"""
 
39
 
20
40
import os, sys
21
41
import bzrlib, bzrlib.help, bzrlib.commands
22
 
#<<< Begin (C) Hans Ulrich Niedermann
 
42
import textwrap
23
43
import time
24
44
import re
25
45
 
43
63
 
44
64
    outfile.write(man_preamble % params)
45
65
    outfile.write(man_escape(man_head % params))
46
 
#<<< End (C) Hans Ulrich Niedermann
47
 
    outfile.write(man_escape(getcommand_help()))
48
 
#<<< Begin (C) Hans Ulrich Niedermann
 
66
 
 
67
    outfile.write(man_escape(getcommand_list(params)))
 
68
    outfile.write(man_escape(getcommand_help(params)))
 
69
 
49
70
    outfile.write(man_escape(man_foot % params))
50
71
 
 
72
 
51
73
def man_escape(string):
52
74
    result = string.replace("\\","\\\\")
53
75
    result = result.replace("`","\\`")
54
76
    result = result.replace("'","\\'")
55
77
    result = result.replace("-","\\-")
56
78
    return result
57
 
#<<< End (C) Hans Ulrich Niedermann
58
 
 
59
 
def format_command (cmd):
60
 
    cmdusage = '.TP\n.B %s\n.PP\n' % (bzrlib.help.command_usage(cmd))
61
 
    doc = "%s\n.PP\n.PP\n" % (cmd.__doc__)
62
 
    return cmdusage + doc
63
 
 
64
 
def getcommand_help():
65
 
    output=""
66
 
    command_names = bzrlib.commands.builtin_command_names()
67
 
    command_names.sort()
68
 
    for cmd_name in  command_names:
69
 
        desc = bzrlib.commands.get_cmd_object(cmd_name)
70
 
        output = output + format_command(desc)
 
79
 
 
80
 
 
81
def getcommand_list (params):
 
82
    bzrcmd = params["bzrcmd"]
 
83
    output = '.SH "COMMAND OVERVIEW"\n'
 
84
    command_names = bzrlib.commands.builtin_command_names()
 
85
    command_names.sort()
 
86
    for cmd_name in command_names:
 
87
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
 
88
        if cmd_object.hidden:
 
89
            continue
 
90
        cmd_help = cmd_object.help()
 
91
        if cmd_help:
 
92
            firstline = cmd_help.split('\n', 1)[0]
 
93
            tmp = '.TP\n.B "%s %s"\n%s\n' % (bzrcmd, cmd_name,
 
94
                                                        firstline)
 
95
        else:
 
96
            tmp = '.TP\n.B "%s %s"\n%s\n' % (bzrcmd, cmd_name, "foo")            
 
97
        output = output + tmp
 
98
    return output
 
99
 
 
100
 
 
101
def format_command (params, cmd):
 
102
    subsection_header = '.SS "%s %s"\n' % (params["bzrcmd"], cmd.name())
 
103
    cmdusage = '.TP\n.B "Usage: %s"\n.PP\n' % (bzrlib.help.command_usage(cmd))
 
104
    doc = "%s\n" % (cmd.__doc__)
 
105
    option_str = ""
 
106
    options = cmd.options()
 
107
    # option walk code stolen from bzrlib/help.py
 
108
    if options:
 
109
        option_str = "\nOptions:\n"
 
110
        for option_name, option in sorted(options.items()):
 
111
            l = '    --' + option_name
 
112
            if option.type is not None:
 
113
                l += ' ' + option.argname.upper()
 
114
            short_name = option.short_name()
 
115
            if short_name:
 
116
                assert len(short_name) == 1
 
117
                l += ', -' + short_name
 
118
            l += (30 - len(l)) * ' ' + option.help
 
119
            # TODO: split help over multiple lines with correct indenting and 
 
120
            # wrapping
 
121
            wrapped = textwrap.fill(l, initial_indent='',
 
122
                                    subsequent_indent=30*' ')
 
123
            option_str = option_str + wrapped + '\n'       
 
124
    return subsection_header + cmdusage + doc + option_str
 
125
 
 
126
 
 
127
def getcommand_help(params):
 
128
    output='.SH "COMMAND REFERENCE"\n'
 
129
    command_names = bzrlib.commands.builtin_command_names()
 
130
    command_names.sort()
 
131
    for cmd_name in command_names:
 
132
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
 
133
        if cmd_object.hidden:
 
134
            continue
 
135
        output = output + format_command(params, cmd_object)
71
136
    return output
72
137
 
73
138
 
94
159
) is a project of Canonical Ltd. to develop an open source distributed version control system that is powerful, friendly, and scalable. Version control means a system that keeps track of previous revisions of software source code or similar information and helps people work on it in teams.
95
160
.SS "Warning"
96
161
bazaar-ng is at an early stage of development, and the design is still changing from week to week. This man page here may be inconsistent with itself, with other documentation or with the code, and sometimes refer to features that are planned but not yet written. Comments are still very welcome; please send them to bazaar-ng@lists.canonical.com.
 
162
 
 
163
.SH "USAGE"
 
164
Commands for a number of common use cases.
 
165
 
 
166
.SS "Create a branch"
 
167
    $ cd my-project
 
168
    $ %(bzrcmd)s init
 
169
 
 
170
.SS "Add files to be versioned"
 
171
    $ cd my-project
 
172
    $ %(bzrcmd)s add hello-world.c Makefile
 
173
 
 
174
.SS "Review local changes"
 
175
    $ cd my-project
 
176
    $ %(bzrcmd)s status
 
177
    $ %(bzrcmd)s diff
 
178
 
 
179
.SS "Commit changes to branch"
 
180
    $ cd my-project
 
181
    $ %(bzrcmd)s commit -m \"initial import of files\"
 
182
 
 
183
.SS "Branching off an existing branch"
 
184
    $ %(bzrcmd)s branch http://other.com/project-foo
 
185
    $ cd project-foo
 
186
 
 
187
    $ %(bzrcmd)s branch http://other.com/project-foo foo-by-other
 
188
    $ cd foo-by-other
 
189
    
 
190
    $ %(bzrcmd)s branch foo-by-other foo-with-my-changes
 
191
    $ cd foo-with-my-changes
 
192
 
 
193
.SS "Following upstream changes"
 
194
If you have not modified anything in your local branch:
 
195
    $ cd foo-by-other
 
196
    $ %(bzrcmd)s pull
 
197
 
 
198
If you have modified and committed things in your local branch:
 
199
    $ cd foo-with-my-changes
 
200
    $ %(bzrcmd)s merge
 
201
 
 
202
.SS "Publishing your changes"
 
203
Publishing your branch for the first time:
 
204
    $ cd foo-with-my-changes
 
205
    $ %(bzrcmd)s push sftp://user@host/public_html/foo-with-my-changes
 
206
 
 
207
Publishing your branch subsequently is easier as %(bzrcmd)s remembers the push location:
 
208
    $ cd foo-with-my-changes
 
209
    $ %(bzrcmd)s push
 
210
    
97
211
"""
98
212
 
99
213
man_foot = """\
150
264
.BR http://bazaar.canonical.com/BzrDocumentation
151
265
"""
152
266
 
153
 
#<<< Begin (C) Hans Ulrich Niedermann
154
267
man_preamble = """\
155
268
.\\\" Man page for %(bzrcmd)s (bazaar-ng)
156
269
.\\\"
164
277
 
165
278
if __name__ == '__main__':
166
279
    main()
167
 
#<<< End (C) Hans Ulrich Niedermann