~bzr-pqm/bzr/bzr.dev

4763.2.4 by John Arbash Meinel
merge bzr.2.1 in preparation for NEWS entry.
1
# Copyright (C) 2006-2010 Canonical Ltd
1662.1.17 by Martin Pool
[patch] html manual generator (Alexander Belchenko)
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.
1887.1.1 by Adeodato Simó
Do not separate paragraphs in the copyright statement with blank lines,
12
#
1662.1.17 by Martin Pool
[patch] html manual generator (Alexander Belchenko)
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
4183.7.1 by Sabin Iacob
update FSF mailing address
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
1662.1.17 by Martin Pool
[patch] html manual generator (Alexander Belchenko)
16
6379.6.3 by Jelmer Vernooij
Use absolute_import.
17
from __future__ import absolute_import
18
4927.2.2 by Ian Clatworthy
User Reference as topics
19
"""Generate reStructuredText source for the User Reference Manual.
2666.1.1 by Ian Clatworthy
Bazaar User Reference generated from online help
20
Loosely based on the manpage generator autodoc_man.py.
1662.1.17 by Martin Pool
[patch] html manual generator (Alexander Belchenko)
21
2677.1.4 by Alexander Belchenko
fixes after John's review
22
Written by the Bazaar community.
1662.1.17 by Martin Pool
[patch] html manual generator (Alexander Belchenko)
23
"""
24
25
import os
26
import sys
27
import time
28
29
import bzrlib
30
import bzrlib.help
2666.1.1 by Ian Clatworthy
Bazaar User Reference generated from online help
31
import bzrlib.help_topics
1662.1.17 by Martin Pool
[patch] html manual generator (Alexander Belchenko)
32
import bzrlib.commands
3089.3.16 by Ian Clatworthy
Dump help topics into text files in doc/en/user-reference
33
import bzrlib.osutils
1662.1.17 by Martin Pool
[patch] html manual generator (Alexander Belchenko)
34
35
36
def get_filename(options):
37
    """Provides name of manual"""
38
    return "%s_man.txt" % (options.bzr_name)
39
40
41
def infogen(options, outfile):
42
    """Create manual in RSTX format"""
43
    t = time.time()
44
    tt = time.gmtime(t)
45
    params = \
46
           { "bzrcmd": options.bzr_name,
47
             "datestamp": time.strftime("%Y-%m-%d",tt),
48
             "timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
49
             "version": bzrlib.__version__,
50
             }
3089.3.17 by Ian Clatworthy
Fix case where filename not given
51
    nominated_filename = getattr(options, 'filename', None)
3089.3.16 by Ian Clatworthy
Dump help topics into text files in doc/en/user-reference
52
    if nominated_filename is None:
53
        topic_dir = None
54
    else:
55
        topic_dir = bzrlib.osutils.dirname(nominated_filename)
1662.1.17 by Martin Pool
[patch] html manual generator (Alexander Belchenko)
56
    outfile.write(rstx_preamble % params)
57
    outfile.write(rstx_head % params)
3089.3.16 by Ian Clatworthy
Dump help topics into text files in doc/en/user-reference
58
    outfile.write(_get_body(params, topic_dir))
1662.1.17 by Martin Pool
[patch] html manual generator (Alexander Belchenko)
59
    outfile.write(rstx_foot % params)
60
61
3089.3.16 by Ian Clatworthy
Dump help topics into text files in doc/en/user-reference
62
def _get_body(params, topic_dir):
2666.1.1 by Ian Clatworthy
Bazaar User Reference generated from online help
63
    """Build the manual content."""
64
    from bzrlib.help_topics import SECT_CONCEPT, SECT_LIST, SECT_PLUGIN
65
    registry = bzrlib.help_topics.topic_registry
66
    result = []
3089.3.16 by Ian Clatworthy
Dump help topics into text files in doc/en/user-reference
67
    result.append(_get_section(registry, SECT_CONCEPT, "Concepts",
68
        output_dir=topic_dir))
69
    result.append(_get_section(registry, SECT_LIST, "Lists",
70
        output_dir=topic_dir))
4927.2.2 by Ian Clatworthy
User Reference as topics
71
    result.append(_get_commands_section(registry, output_dir=topic_dir))
2666.1.1 by Ian Clatworthy
Bazaar User Reference generated from online help
72
    return "\n".join(result)
73
74
3089.3.16 by Ian Clatworthy
Dump help topics into text files in doc/en/user-reference
75
def _get_section(registry, section, title, hdg_level1="#", hdg_level2="=",
76
        output_dir=None):
77
    """Build the manual part from topics matching that section.
78
    
79
    If output_dir is not None, topics are dumped into text files there
80
    during processing, as well as being included in the return result.
81
    """
4927.2.10 by Ian Clatworthy
fix test failures
82
    file_per_topic = output_dir is not None
2666.1.1 by Ian Clatworthy
Bazaar User Reference generated from online help
83
    lines = [title, hdg_level1 * len(title), ""]
4927.2.10 by Ian Clatworthy
fix test failures
84
    if file_per_topic:
4927.2.2 by Ian Clatworthy
User Reference as topics
85
        lines.extend([".. toctree::", "   :maxdepth: 1", ""])
2677.1.4 by Alexander Belchenko
fixes after John's review
86
4927.2.2 by Ian Clatworthy
User Reference as topics
87
    topics = sorted(registry.get_topics_for_section(section))
2666.1.1 by Ian Clatworthy
Bazaar User Reference generated from online help
88
    for topic in topics:
89
        help = registry.get_detail(topic)
4927.2.2 by Ian Clatworthy
User Reference as topics
90
        heading, text = help.split("\n", 1)
3089.3.1 by Ian Clatworthy
move reference material out of User Guide into User Reference
91
        if not text.startswith(hdg_level2):
4927.2.2 by Ian Clatworthy
User Reference as topics
92
            underline = hdg_level2 * len(heading)
93
            help = "%s\n%s\n\n%s\n\n" % (heading, underline, text)
94
        else:
95
            help = "%s\n%s\n\n" % (heading, text)
4927.2.10 by Ian Clatworthy
fix test failures
96
        if file_per_topic:
4927.2.2 by Ian Clatworthy
User Reference as topics
97
            topic_id = _dump_text(output_dir, topic, help)
98
            lines.append("   %s" % topic_id)
99
        else:
100
            lines.append(help)
101
2666.1.1 by Ian Clatworthy
Bazaar User Reference generated from online help
102
    return "\n" + "\n".join(lines) + "\n"
103
104
3089.3.1 by Ian Clatworthy
move reference material out of User Guide into User Reference
105
def _get_commands_section(registry, title="Commands", hdg_level1="#",
4927.2.2 by Ian Clatworthy
User Reference as topics
106
        hdg_level2="=", output_dir=None):
3565.2.1 by Christophe Troestler
(trivial) Corrected typos.
107
    """Build the commands reference section of the manual."""
4927.2.10 by Ian Clatworthy
fix test failures
108
    file_per_topic = output_dir is not None
2666.1.1 by Ian Clatworthy
Bazaar User Reference generated from online help
109
    lines = [title, hdg_level1 * len(title), ""]
4927.2.10 by Ian Clatworthy
fix test failures
110
    if file_per_topic:
4927.2.2 by Ian Clatworthy
User Reference as topics
111
        lines.extend([".. toctree::", "   :maxdepth: 1", ""])
112
2666.1.1 by Ian Clatworthy
Bazaar User Reference generated from online help
113
    cmds = sorted(bzrlib.commands.builtin_command_names())
114
    for cmd_name in cmds:
115
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
116
        if cmd_object.hidden:
117
            continue
118
        heading = cmd_name
4927.2.2 by Ian Clatworthy
User Reference as topics
119
        underline = hdg_level2 * len(heading)
2677.1.2 by Alexander Belchenko
bzr_man: see also topics as cross-reference links
120
        text = cmd_object.get_help_text(plain=False, see_also_as_links=True)
4927.2.2 by Ian Clatworthy
User Reference as topics
121
        help = "%s\n%s\n\n%s\n\n" % (heading, underline, text)
4927.2.10 by Ian Clatworthy
fix test failures
122
        if file_per_topic:
4927.2.2 by Ian Clatworthy
User Reference as topics
123
            topic_id = _dump_text(output_dir, cmd_name, help)
124
            lines.append("   %s" % topic_id)
125
        else:
126
            lines.append(help)
127
2666.1.1 by Ian Clatworthy
Bazaar User Reference generated from online help
128
    return "\n" + "\n".join(lines) + "\n"
1662.1.17 by Martin Pool
[patch] html manual generator (Alexander Belchenko)
129
130
4927.2.2 by Ian Clatworthy
User Reference as topics
131
def _dump_text(output_dir, topic, text):
132
    """Dump text for a topic to a file."""
133
    topic_id = "%s-%s" % (topic, "help")
134
    filename = bzrlib.osutils.pathjoin(output_dir, topic_id + ".txt")
135
    f =  open(filename, "w")
136
    f.writelines(text)
137
    f.close()
138
    return topic_id
139
140
1662.1.17 by Martin Pool
[patch] html manual generator (Alexander Belchenko)
141
##
142
# TEMPLATES
143
2666.1.1 by Ian Clatworthy
Bazaar User Reference generated from online help
144
rstx_preamble = """.. This file is autogenerated from the output of
145
..     %(bzrcmd)s help topics
1662.1.17 by Martin Pool
[patch] html manual generator (Alexander Belchenko)
146
..     %(bzrcmd)s help commands
147
..     %(bzrcmd)s help <cmd>
148
..
149
.. Generation time: %(timestamp)s
150
2666.1.1 by Ian Clatworthy
Bazaar User Reference generated from online help
151
"""
152
153
154
rstx_head = """\
3089.3.1 by Ian Clatworthy
move reference material out of User Guide into User Reference
155
#####################
2666.1.1 by Ian Clatworthy
Bazaar User Reference generated from online help
156
Bazaar User Reference
3089.3.1 by Ian Clatworthy
move reference material out of User Guide into User Reference
157
#####################
2666.1.1 by Ian Clatworthy
Bazaar User Reference generated from online help
158
159
About This Manual
3089.3.1 by Ian Clatworthy
move reference material out of User Guide into User Reference
160
#################
2666.1.1 by Ian Clatworthy
Bazaar User Reference generated from online help
161
162
This manual is generated from Bazaar's online help. To use
163
the online help system, try the following commands.
164
165
    Introduction including a list of commonly used commands::
166
167
        bzr help
168
169
    List of topics and a summary of each::
170
171
        bzr help topics
172
173
    List of commands and a summary of each::
174
175
        bzr help commands
176
177
    More information about a particular topic or command::
178
179
        bzr help topic-or-command-name
180
181
The following web sites provide further information on Bazaar:
182
4927.2.2 by Ian Clatworthy
User Reference as topics
183
:Home page:                     http://bazaar.canonical.com/
184
:Official docs:                 http://doc.bazaar.canonical.com/
2666.1.1 by Ian Clatworthy
Bazaar User Reference generated from online help
185
:Launchpad:                     https://launchpad.net/bzr/
1662.1.17 by Martin Pool
[patch] html manual generator (Alexander Belchenko)
186
"""
187
188
189
rstx_foot = """
190
"""