← 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: Canonical.com Patch Queue Manager
  • Date: 2007-08-08 11:31:10 UTC
  • mfrom: (2677.1.5 bzr_man)
  • Revision ID: pqm@pqm.ubuntu.com-20070808113110-acathx9d9mpfo80z
IE-safe bzr_man.html, cross-reference links for `see also' topics
 (bialix,r=john,r=ian)

Show diffs side-by-side

added added

removed removed

Lines of Context:
tools/doc_generate/autodoc_rstx.py
17
17
"""Generate ReStructuredText source for the User Reference Manual.
18
18
Loosely based on the manpage generator autodoc_man.py.
19
19
 
20
 
Written by Alexander Belchenko and the Bazaar community.
 
20
Written by the Bazaar community.
21
21
"""
22
22
 
23
23
import os
68
68
    """Build the manual part from topics matching that section."""
69
69
    topics = sorted(registry.get_topics_for_section(section))
70
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
 
71
85
    for topic in topics:
72
86
        help = registry.get_detail(topic)
73
87
        heading,text = help.split("\n", 1)
75
89
        lines.append(hdg_level2 * len(heading))
76
90
        lines.append(text)
77
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
 
78
100
    return "\n" + "\n".join(lines) + "\n"
79
101
 
80
102
 
88
110
        if cmd_object.hidden:
89
111
            continue
90
112
        heading = cmd_name
91
 
        text = cmd_object.get_help_text(plain=False)
 
113
        text = cmd_object.get_help_text(plain=False, see_also_as_links=True)
92
114
        lines.append(heading)
93
115
        lines.append(hdg_level2 * len(heading))
94
116
        lines.append(text)