← 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: Robert Collins
  • Date: 2007-11-09 17:50:31 UTC
  • mto: This revision was merged to the branch mainline in revision 2988.
  • Revision ID: robertc@robertcollins.net-20071109175031-agaiy6530rvbprmb
Change (without backwards compatibility) the
iter_lines_added_or_present_in_versions VersionedFile API to yield the
text version that each line is being returned from. This is useful for
reconcile in determining what inventories reference what texts.
(Robert Collins)

Show diffs side-by-side

added added

removed removed

Lines of Context:
tools/doc_generate/autodoc_rstx.py
 
1
# Copyright 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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  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 textwrap
 
26
import time
 
27
 
 
28
import bzrlib
 
29
import bzrlib.help
 
30
import bzrlib.help_topics
 
31
import bzrlib.commands
 
32
 
 
33
 
 
34
def get_filename(options):
 
35
    """Provides name of manual"""
 
36
    return "%s_man.txt" % (options.bzr_name)
 
37
 
 
38
 
 
39
def infogen(options, outfile):
 
40
    """Create manual in RSTX format"""
 
41
    t = time.time()
 
42
    tt = time.gmtime(t)
 
43
    params = \
 
44
           { "bzrcmd": options.bzr_name,
 
45
             "datestamp": time.strftime("%Y-%m-%d",tt),
 
46
             "timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
 
47
             "version": bzrlib.__version__,
 
48
             }
 
49
    outfile.write(rstx_preamble % params)
 
50
    outfile.write(rstx_head % params)
 
51
    outfile.write(_get_body(params))
 
52
    outfile.write(rstx_foot % params)
 
53
 
 
54
 
 
55
def _get_body(params):
 
56
    """Build the manual content."""
 
57
    from bzrlib.help_topics import SECT_CONCEPT, SECT_LIST, SECT_PLUGIN
 
58
    registry = bzrlib.help_topics.topic_registry
 
59
    result = []
 
60
    result.append(_get_section(registry, SECT_CONCEPT, "Concepts"))
 
61
    result.append(_get_section(registry, SECT_LIST, "Lists"))
 
62
    result.append(_get_commands_section(registry))
 
63
    #result.append(_get_section(registry, SECT_PLUGIN, "Core Plug-ins"))
 
64
    return "\n".join(result)
 
65
 
 
66
 
 
67
def _get_section(registry, section, title, hdg_level1="=", hdg_level2="-"):
 
68
    """Build the manual part from topics matching that section."""
 
69
    topics = sorted(registry.get_topics_for_section(section))
 
70
    lines = [title, hdg_level1 * len(title), ""]
 
71
 
 
72
    # docutils treats section heading as implicit link target.
 
73
    # But in some cases topic and heading are different, e.g.:
 
74
    #
 
75
    # `bugs' vs. `Bug Trackers'
 
76
    # `working-tree' vs. `Working Trees'
 
77
    #
 
78
    # So for building proper cross-reference between topic names
 
79
    # and corresponding sections in document, we need provide
 
80
    # simple glue in the form:
 
81
    #
 
82
    # .. _topic: `heading`_
 
83
    links_glue = []
 
84
 
 
85
    for topic in topics:
 
86
        help = registry.get_detail(topic)
 
87
        heading,text = help.split("\n", 1)
 
88
        lines.append(heading)
 
89
        lines.append(hdg_level2 * len(heading))
 
90
        lines.append(text)
 
91
        lines.append('')
 
92
        # check that topic match heading
 
93
        if topic != heading.lower():
 
94
            links_glue.append((topic, heading))
 
95
 
 
96
    # provide links glue for topics that don't match headings
 
97
    lines.extend([".. _%s: `%s`_" % i for i in links_glue])
 
98
    lines.append('')
 
99
 
 
100
    return "\n" + "\n".join(lines) + "\n"
 
101
 
 
102
 
 
103
def _get_commands_section(registry, title="Commands", hdg_level1="=",
 
104
                          hdg_level2="-"):
 
105
    """Build the comands reference section of the manual."""
 
106
    lines = [title, hdg_level1 * len(title), ""]
 
107
    cmds = sorted(bzrlib.commands.builtin_command_names())
 
108
    for cmd_name in cmds:
 
109
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
 
110
        if cmd_object.hidden:
 
111
            continue
 
112
        heading = cmd_name
 
113
        text = cmd_object.get_help_text(plain=False, see_also_as_links=True)
 
114
        lines.append(heading)
 
115
        lines.append(hdg_level2 * len(heading))
 
116
        lines.append(text)
 
117
        lines.append('')
 
118
    return "\n" + "\n".join(lines) + "\n"
 
119
 
 
120
 
 
121
##
 
122
# TEMPLATES
 
123
 
 
124
rstx_preamble = """.. This file is autogenerated from the output of
 
125
..     %(bzrcmd)s help topics
 
126
..     %(bzrcmd)s help commands
 
127
..     %(bzrcmd)s help <cmd>
 
128
..
 
129
.. Generation time: %(timestamp)s
 
130
 
 
131
"""
 
132
 
 
133
 
 
134
rstx_head = """\
 
135
=====================
 
136
Bazaar User Reference
 
137
=====================
 
138
 
 
139
:Version:   %(version)s
 
140
:Generated: %(datestamp)s
 
141
 
 
142
.. contents::
 
143
 
 
144
-----
 
145
 
 
146
About This Manual
 
147
=================
 
148
 
 
149
This manual is generated from Bazaar's online help. To use
 
150
the online help system, try the following commands.
 
151
 
 
152
    Introduction including a list of commonly used commands::
 
153
 
 
154
        bzr help
 
155
 
 
156
    List of topics and a summary of each::
 
157
 
 
158
        bzr help topics
 
159
 
 
160
    List of commands and a summary of each::
 
161
 
 
162
        bzr help commands
 
163
 
 
164
    More information about a particular topic or command::
 
165
 
 
166
        bzr help topic-or-command-name
 
167
 
 
168
The following web sites provide further information on Bazaar:
 
169
 
 
170
:Home page:                     http://www.bazaar-vcs.org/
 
171
:Official docs:                 http://doc.bazaar-vcs.org/
 
172
:Launchpad:                     https://launchpad.net/bzr/
 
173
"""
 
174
 
 
175
 
 
176
rstx_foot = """
 
177
"""