/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to bzrlib/doc_generate/autodoc_rstx.py

  • Committer: John Arbash Meinel
  • Date: 2009-12-22 16:28:47 UTC
  • mto: This revision was merged to the branch mainline in revision 4922.
  • Revision ID: john@arbash-meinel.com-20091222162847-tvnsc69to4l4uf5r
Implement a permute_for_extension helper.

Use it for all of the 'simple' extension permutations.
It basically permutes all tests in the current module, by setting TestCase.module.
Which works well for most of our extension tests. Some had more advanced
handling of permutations (extra permutations, custom vars, etc.)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/doc_generate/autodoc_rstx.py
 
1
# Copyright (C) 2006-2007 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., 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
"""
 
22
 
 
23
import os
 
24
import sys
 
25
import time
 
26
 
 
27
import bzrlib
 
28
import bzrlib.help
 
29
import bzrlib.help_topics
 
30
import bzrlib.commands
 
31
import bzrlib.osutils
 
32
 
 
33
 
 
34
# Set this to True to generate a file per topic.
 
35
# This probably ought to be an option. The files probably
 
36
# ought to be prefixed with their section name as well so
 
37
# there's zero risk of clashing with a standard sphinx
 
38
# topic (like search.html).
 
39
FILE_PER_TOPIC = False
 
40
 
 
41
 
 
42
def get_filename(options):
 
43
    """Provides name of manual"""
 
44
    return "%s_man.txt" % (options.bzr_name)
 
45
 
 
46
 
 
47
def infogen(options, outfile):
 
48
    """Create manual in RSTX format"""
 
49
    t = time.time()
 
50
    tt = time.gmtime(t)
 
51
    params = \
 
52
           { "bzrcmd": options.bzr_name,
 
53
             "datestamp": time.strftime("%Y-%m-%d",tt),
 
54
             "timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
 
55
             "version": bzrlib.__version__,
 
56
             }
 
57
    nominated_filename = getattr(options, 'filename', None)
 
58
    if nominated_filename is None:
 
59
        topic_dir = None
 
60
    else:
 
61
        topic_dir = bzrlib.osutils.dirname(nominated_filename)
 
62
    outfile.write(rstx_preamble % params)
 
63
    outfile.write(rstx_head % params)
 
64
    outfile.write(_get_body(params, topic_dir))
 
65
    outfile.write(rstx_foot % params)
 
66
 
 
67
 
 
68
def _get_body(params, topic_dir):
 
69
    """Build the manual content."""
 
70
    from bzrlib.help_topics import SECT_CONCEPT, SECT_LIST, SECT_PLUGIN
 
71
    registry = bzrlib.help_topics.topic_registry
 
72
    result = []
 
73
    result.append(_get_section(registry, SECT_CONCEPT, "Concepts",
 
74
        output_dir=topic_dir))
 
75
    result.append(_get_section(registry, SECT_LIST, "Lists",
 
76
        output_dir=topic_dir))
 
77
    result.append(_get_commands_section(registry))
 
78
    #result.append(_get_section(registry, SECT_PLUGIN, "Standard Plug-ins"))
 
79
    return "\n".join(result)
 
80
 
 
81
 
 
82
def _get_section(registry, section, title, hdg_level1="#", hdg_level2="=",
 
83
        output_dir=None):
 
84
    """Build the manual part from topics matching that section.
 
85
    
 
86
    If output_dir is not None, topics are dumped into text files there
 
87
    during processing, as well as being included in the return result.
 
88
    """
 
89
    topics = sorted(registry.get_topics_for_section(section))
 
90
    lines = [title, hdg_level1 * len(title), ""]
 
91
 
 
92
    # docutils treats section heading as implicit link target.
 
93
    # But in some cases topic and heading are different, e.g.:
 
94
    #
 
95
    # `bugs' vs. `Bug Trackers'
 
96
    # `working-tree' vs. `Working Trees'
 
97
    #
 
98
    # So for building proper cross-reference between topic names
 
99
    # and corresponding sections in document, we need provide
 
100
    # simple glue in the form:
 
101
    #
 
102
    # .. _topic: `heading`_
 
103
    links_glue = []
 
104
 
 
105
    for topic in topics:
 
106
        help = registry.get_detail(topic)
 
107
        heading,text = help.split("\n", 1)
 
108
        lines.append(heading)
 
109
        if not text.startswith(hdg_level2):
 
110
            lines.append(hdg_level2 * len(heading))
 
111
        lines.append(text)
 
112
        lines.append('')
 
113
        # check that topic match heading
 
114
        if topic != heading.lower():
 
115
            links_glue.append((topic, heading))
 
116
        # dump the text if requested
 
117
        if output_dir is not None:
 
118
            out_file = bzrlib.osutils.pathjoin(output_dir, topic + ".txt")
 
119
            _dump_text(out_file, help)
 
120
 
 
121
    # provide links glue for topics that don't match headings
 
122
    lines.extend([".. _%s: `%s`_" % i for i in links_glue])
 
123
    lines.append('')
 
124
 
 
125
    return "\n" + "\n".join(lines) + "\n"
 
126
 
 
127
 
 
128
def _dump_text(filename, text):
 
129
    """Dump text to filename."""
 
130
    if not FILE_PER_TOPIC:
 
131
        return
 
132
    f =  open(filename, "w")
 
133
    f.writelines(text)
 
134
    f.close()
 
135
 
 
136
 
 
137
def _get_commands_section(registry, title="Commands", hdg_level1="#",
 
138
                          hdg_level2="="):
 
139
    """Build the commands reference section of the manual."""
 
140
    lines = [title, hdg_level1 * len(title), ""]
 
141
    cmds = sorted(bzrlib.commands.builtin_command_names())
 
142
    for cmd_name in cmds:
 
143
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
 
144
        if cmd_object.hidden:
 
145
            continue
 
146
        heading = cmd_name
 
147
        text = cmd_object.get_help_text(plain=False, see_also_as_links=True)
 
148
        lines.append(heading)
 
149
        lines.append(hdg_level2 * len(heading))
 
150
        lines.append(text)
 
151
        lines.append('')
 
152
    return "\n" + "\n".join(lines) + "\n"
 
153
 
 
154
 
 
155
##
 
156
# TEMPLATES
 
157
 
 
158
rstx_preamble = """.. This file is autogenerated from the output of
 
159
..     %(bzrcmd)s help topics
 
160
..     %(bzrcmd)s help commands
 
161
..     %(bzrcmd)s help <cmd>
 
162
..
 
163
.. Generation time: %(timestamp)s
 
164
 
 
165
"""
 
166
 
 
167
 
 
168
rstx_head = """\
 
169
#####################
 
170
Bazaar User Reference
 
171
#####################
 
172
 
 
173
About This Manual
 
174
#################
 
175
 
 
176
This manual is generated from Bazaar's online help. To use
 
177
the online help system, try the following commands.
 
178
 
 
179
    Introduction including a list of commonly used commands::
 
180
 
 
181
        bzr help
 
182
 
 
183
    List of topics and a summary of each::
 
184
 
 
185
        bzr help topics
 
186
 
 
187
    List of commands and a summary of each::
 
188
 
 
189
        bzr help commands
 
190
 
 
191
    More information about a particular topic or command::
 
192
 
 
193
        bzr help topic-or-command-name
 
194
 
 
195
The following web sites provide further information on Bazaar:
 
196
 
 
197
:Home page:                     http://www.bazaar-vcs.org/
 
198
:Official docs:                 http://doc.bazaar-vcs.org/
 
199
:Launchpad:                     https://launchpad.net/bzr/
 
200
"""
 
201
 
 
202
 
 
203
rstx_foot = """
 
204
"""