← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/doc_generate/autodoc_rstx.py

  • Committer: Ian Clatworthy
  • Date: 2010-01-08 07:37:25 UTC
  • mfrom: (4927.2.10 user-ref-topics)
  • mto: This revision was merged to the branch mainline in revision 4945.
  • Revision ID: ian.clatworthy@canonical.com-20100108073725-04icssis1mvkncfc
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.
31
31
import bzrlib.osutils
32
32
 
33
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
34
def get_filename(options):
43
35
    """Provides name of manual"""
44
36
    return "%s_man.txt" % (options.bzr_name)
74
66
        output_dir=topic_dir))
75
67
    result.append(_get_section(registry, SECT_LIST, "Lists",
76
68
        output_dir=topic_dir))
77
 
    result.append(_get_commands_section(registry))
78
 
    #result.append(_get_section(registry, SECT_PLUGIN, "Standard Plug-ins"))
 
69
    result.append(_get_commands_section(registry, output_dir=topic_dir))
79
70
    return "\n".join(result)
80
71
 
81
72
 
86
77
    If output_dir is not None, topics are dumped into text files there
87
78
    during processing, as well as being included in the return result.
88
79
    """
 
80
    file_per_topic = output_dir is not None
 
81
    lines = [title, hdg_level1 * len(title), ""]
 
82
    if file_per_topic:
 
83
        lines.extend([".. toctree::", "   :maxdepth: 1", ""])
 
84
 
89
85
    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
86
    for topic in topics:
106
87
        help = registry.get_detail(topic)
107
 
        heading,text = help.split("\n", 1)
108
 
        lines.append(heading)
 
88
        heading, text = help.split("\n", 1)
109
89
        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('')
 
90
            underline = hdg_level2 * len(heading)
 
91
            help = "%s\n%s\n\n%s\n\n" % (heading, underline, text)
 
92
        else:
 
93
            help = "%s\n%s\n\n" % (heading, text)
 
94
        if file_per_topic:
 
95
            topic_id = _dump_text(output_dir, topic, help)
 
96
            lines.append("   %s" % topic_id)
 
97
        else:
 
98
            lines.append(help)
124
99
 
125
100
    return "\n" + "\n".join(lines) + "\n"
126
101
 
127
102
 
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
103
def _get_commands_section(registry, title="Commands", hdg_level1="#",
138
 
                          hdg_level2="="):
 
104
        hdg_level2="=", output_dir=None):
139
105
    """Build the commands reference section of the manual."""
 
106
    file_per_topic = output_dir is not None
140
107
    lines = [title, hdg_level1 * len(title), ""]
 
108
    if file_per_topic:
 
109
        lines.extend([".. toctree::", "   :maxdepth: 1", ""])
 
110
 
141
111
    cmds = sorted(bzrlib.commands.builtin_command_names())
142
112
    for cmd_name in cmds:
143
113
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
144
114
        if cmd_object.hidden:
145
115
            continue
146
116
        heading = cmd_name
 
117
        underline = hdg_level2 * len(heading)
147
118
        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('')
 
119
        help = "%s\n%s\n\n%s\n\n" % (heading, underline, text)
 
120
        if file_per_topic:
 
121
            topic_id = _dump_text(output_dir, cmd_name, help)
 
122
            lines.append("   %s" % topic_id)
 
123
        else:
 
124
            lines.append(help)
 
125
 
152
126
    return "\n" + "\n".join(lines) + "\n"
153
127
 
154
128
 
 
129
def _dump_text(output_dir, topic, text):
 
130
    """Dump text for a topic to a file."""
 
131
    topic_id = "%s-%s" % (topic, "help")
 
132
    filename = bzrlib.osutils.pathjoin(output_dir, topic_id + ".txt")
 
133
    f =  open(filename, "w")
 
134
    f.writelines(text)
 
135
    f.close()
 
136
    return topic_id
 
137
 
 
138
 
155
139
##
156
140
# TEMPLATES
157
141
 
194
178
 
195
179
The following web sites provide further information on Bazaar:
196
180
 
197
 
:Home page:                     http://www.bazaar-vcs.org/
198
 
:Official docs:                 http://doc.bazaar-vcs.org/
 
181
:Home page:                     http://bazaar.canonical.com/
 
182
:Official docs:                 http://doc.bazaar.canonical.com/
199
183
:Launchpad:                     https://launchpad.net/bzr/
200
184
"""
201
185