/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: Ian Clatworthy
  • Date: 2010-01-03 02:56:11 UTC
  • mto: (4944.1.1 integration)
  • mto: This revision was merged to the branch mainline in revision 4945.
  • Revision ID: ian.clatworthy@canonical.com-20100103025611-pttb5q6arsr4hnmo
User Reference as topics

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/doc_generate/autodoc_rstx.py
14
14
# along with this program; if not, write to the Free Software
15
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16
16
 
17
 
"""Generate ReStructuredText source for the User Reference Manual.
 
17
"""Generate reStructuredText source for the User Reference Manual.
18
18
Loosely based on the manpage generator autodoc_man.py.
19
19
 
20
20
Written by the Bazaar community.
36
36
# ought to be prefixed with their section name as well so
37
37
# there's zero risk of clashing with a standard sphinx
38
38
# topic (like search.html).
39
 
FILE_PER_TOPIC = False
 
39
FILE_PER_TOPIC = True
40
40
 
41
41
 
42
42
def get_filename(options):
74
74
        output_dir=topic_dir))
75
75
    result.append(_get_section(registry, SECT_LIST, "Lists",
76
76
        output_dir=topic_dir))
77
 
    result.append(_get_commands_section(registry))
78
 
    #result.append(_get_section(registry, SECT_PLUGIN, "Standard Plug-ins"))
 
77
    result.append(_get_commands_section(registry, output_dir=topic_dir))
79
78
    return "\n".join(result)
80
79
 
81
80
 
86
85
    If output_dir is not None, topics are dumped into text files there
87
86
    during processing, as well as being included in the return result.
88
87
    """
89
 
    topics = sorted(registry.get_topics_for_section(section))
90
88
    lines = [title, hdg_level1 * len(title), ""]
 
89
    if FILE_PER_TOPIC:
 
90
        lines.extend([".. toctree::", "   :maxdepth: 1", ""])
91
91
 
92
92
    # docutils treats section heading as implicit link target.
93
93
    # But in some cases topic and heading are different, e.g.:
102
102
    # .. _topic: `heading`_
103
103
    links_glue = []
104
104
 
 
105
    topics = sorted(registry.get_topics_for_section(section))
105
106
    for topic in topics:
106
107
        help = registry.get_detail(topic)
107
 
        heading,text = help.split("\n", 1)
108
 
        lines.append(heading)
 
108
        heading, text = help.split("\n", 1)
109
109
        if not text.startswith(hdg_level2):
110
 
            lines.append(hdg_level2 * len(heading))
111
 
        lines.append(text)
112
 
        lines.append('')
 
110
            underline = hdg_level2 * len(heading)
 
111
            help = "%s\n%s\n\n%s\n\n" % (heading, underline, text)
 
112
        else:
 
113
            help = "%s\n%s\n\n" % (heading, text)
 
114
        if FILE_PER_TOPIC:
 
115
            topic_id = _dump_text(output_dir, topic, help)
 
116
            lines.append("   %s" % topic_id)
 
117
        else:
 
118
            lines.append(help)
 
119
 
113
120
        # check that topic match heading
114
121
        if topic != heading.lower():
115
122
            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
123
 
121
124
    # provide links glue for topics that don't match headings
122
 
    lines.extend([".. _%s: `%s`_" % i for i in links_glue])
123
 
    lines.append('')
 
125
    #lines.append('')
 
126
    #lines.extend([".. _%s: `%s`_" % i for i in links_glue])
 
127
    #lines.append('')
124
128
 
125
129
    return "\n" + "\n".join(lines) + "\n"
126
130
 
127
131
 
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
132
def _get_commands_section(registry, title="Commands", hdg_level1="#",
138
 
                          hdg_level2="="):
 
133
        hdg_level2="=", output_dir=None):
139
134
    """Build the commands reference section of the manual."""
140
135
    lines = [title, hdg_level1 * len(title), ""]
 
136
    if FILE_PER_TOPIC:
 
137
        lines.extend([".. toctree::", "   :maxdepth: 1", ""])
 
138
 
141
139
    cmds = sorted(bzrlib.commands.builtin_command_names())
142
140
    for cmd_name in cmds:
143
141
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
144
142
        if cmd_object.hidden:
145
143
            continue
146
144
        heading = cmd_name
 
145
        underline = hdg_level2 * len(heading)
147
146
        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('')
 
147
        help = "%s\n%s\n\n%s\n\n" % (heading, underline, text)
 
148
        if FILE_PER_TOPIC:
 
149
            topic_id = _dump_text(output_dir, cmd_name, help)
 
150
            lines.append("   %s" % topic_id)
 
151
        else:
 
152
            lines.append(help)
 
153
 
152
154
    return "\n" + "\n".join(lines) + "\n"
153
155
 
154
156
 
 
157
def _dump_text(output_dir, topic, text):
 
158
    """Dump text for a topic to a file."""
 
159
    topic_id = "%s-%s" % (topic, "help")
 
160
    filename = bzrlib.osutils.pathjoin(output_dir, topic_id + ".txt")
 
161
    f =  open(filename, "w")
 
162
    f.writelines(text)
 
163
    f.close()
 
164
    return topic_id
 
165
 
 
166
 
155
167
##
156
168
# TEMPLATES
157
169
 
194
206
 
195
207
The following web sites provide further information on Bazaar:
196
208
 
197
 
:Home page:                     http://www.bazaar-vcs.org/
198
 
:Official docs:                 http://doc.bazaar-vcs.org/
 
209
:Home page:                     http://bazaar.canonical.com/
 
210
:Official docs:                 http://doc.bazaar.canonical.com/
199
211
:Launchpad:                     https://launchpad.net/bzr/
200
212
"""
201
213