~bzr-pqm/bzr/bzr.dev

# Copyright (C) 2010 Canonical Ltd
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

"""A sphinx/docutil writer producing texinfo output."""

from docutils import (
    nodes,
    writers,
    )

DEBUG = 0

class TexinfoWriter(writers.Writer):

    supported = ('texinfo',)
    settings_spec = ('No options here.', '', ())
    settings_defaults = {}

    output = None

    def __init__(self, builder):
        writers.Writer.__init__(self)
        self.builder = builder

    def translate(self):
        visitor = TexinfoTranslator(self.document, self.builder)
        self.document.walkabout(visitor)
        self.output = visitor.body


class TexinfoTranslator(nodes.NodeVisitor):

    section_names = ['chapter', 'section', 'subsection', 'subsubsection']
    """texinfo section names differ from the sphinx ones.

    Since this can be confusing, the correspondences are shown below
    (shpinx -> texinfo):
    part       -> chapter
    chapter    -> section
    section    -> subsection
    subsection -> subsubsection

    Additionally, sphinx defines subsubsections and paragraphs which are
    handled as @heading (unnumbered).
    """

    def __init__(self, document, builder):
        nodes.NodeVisitor.__init__(self, document)
        self.builder = builder
        # toctree uses some nodes for different purposes (namely:
        # compact_paragraph, bullet_list) that needs to know when they are
        # processing a toctree.
        self.in_toctree = False
        # sections can be embedded and produce different directives depending
        # on the depth.
        self.section_level = -1
        # By default paragraghs are separated by newlines, but there are some
        # exceptions that set it to '' for some subtrees instead
        self.paragraph_sep = '\n'

    # The whole document

    def visit_document(self, node):
        if DEBUG:
            import sys
            sys.stdout.write(node.pformat().encode('utf8'))
        set_item_list_collector(node, 'text')

    def depart_document(self, node):
        # FIXME: info requires a Top node for each info file, but unless we
        # chose a global layout to divide the overall documentation into a set
        # of info files, there is no criteria to decide for a title.
        top_cmd = '''\
This file has been converted using a beta rst->texinfo converter. 
Most of the info links are currently bogus, don't report bugs about them,
this is currently worked on.
@node Top
@top Placeholder
'''
        self.body = top_cmd + ''.join(node['text'])

    # Layout

    def visit_section(self, node):
        self.section_level += 1
        set_item_list_collector(node, 'text')

    def depart_section(self, node):
        title = node['title']
        ids = node.get('ids', [])
        try:
            section_name = self.section_names[self.section_level]
        except IndexError:
            # Just use @heading, it's not numbered anyway
            section_name = 'heading'
        if ids:
            # There shouldn't be different ids for a section, so until we
            # encounter bugs, just take the first one.
            node_cmd = '@node %s\n' % (ids[0],)
        else:
            node_cmd = ''
        section_cmd = '@%s %s\n' % (section_name, title)
        text = ''.join(node['text'])
        node.parent.collect_text(node_cmd + section_cmd + text)
        self.section_level -= 1

    def visit_topic(self, node):
        pass

    def depart_topic(self, node):
        pass

    def visit_compound(self, node):
        # compound is new in sphinx >= 1.0 and just add a optional layer so we
        # relay the text to the parent when it occurs. This may requires a
        # cleaner approach once we settle on which sphinx versions we want to
        # support.
        set_item_list_collector(node, 'text')

    def depart_compound(self, node):
        text = ''.join(node['text'])
        node.parent.collect_text(text)

    def visit_paragraph(self, node):
        set_item_list_collector(node, 'text')

    def depart_paragraph(self, node):
        # End the paragraph with a new line (or '' depending on the parent) and
        # leave a blank line after it.
        text = ''.join(node['text']) + self.paragraph_sep * 2
        node.parent.collect_text(text)

    def visit_compact_paragraph(self, node):
        set_item_list_collector(node, 'text')
        if node.has_key('toctree'):
            self.in_toctree = True
        elif self.in_toctree:
            set_item_collector(node, 'reference')

    def depart_compact_paragraph(self, node):
        # FIXME: Using a different visitor specific to toctree may be a better
        # design and makes code clearer. -- vila 20100708
        if node.has_key('toctree'):
            if node['text']:
                node.parent.collect_text('@menu\n')
                node.parent.collect_text(''.join(node['text']))
                node.parent.collect_text('@end menu\n')
            self.in_toctree = False
        elif self.in_toctree:
            # * FIRST-ENTRY-NAME:(FILENAME)NODENAME.     DESCRIPTION
            # XXX: the file name should probably be adjusted to the targeted
            # info file name
            node_name, file_name, entry_name = node['reference']
            if not node_name:
                node_name = entry_name
            description = '' # We can't specify a description in rest AFAICS
            # XXX: What if :maxdepth: is not 1 ?
            text = '* %s: (%s)%s. %s\n' % (entry_name, file_name,
                                           node_name, description)
            node.parent.collect_text(text)
        else:
            # End the paragraph with a new line (or '' depending on the parent)
            # and leave a blank line after it.
            text = ''.join(node['text']) + self.paragraph_sep * 2
            node.parent.collect_text(text)

    def visit_literal_block(self, node):
        set_item_collector(node, 'text')

    def depart_literal_block(self, node):
        text = '@samp{%s}' % ''.join(node['text']) + self.paragraph_sep * 2
        node.parent.collect_text(text)

    def visit_block_quote(self, node):
        set_item_list_collector(node, 'text')

    def depart_block_quote(self, node):
        node.parent.collect_text('@example\n')
        node.parent.collect_text(''.join(node['text']))
        node.parent.collect_text('@end example\n\n')

    def depart_warning(self, node):
        pass

    def visit_warning(self, node):
        raise nodes.SkipNode # Not implemented yet

    def visit_note(self, node):
        raise nodes.SkipNode # Not implemented yet

    def depart_note(self, node):
        pass

    def visit_footnote(self, node):
        raise nodes.SkipNode # Not implemented yet

    def depart_footnote(self, node):
        pass

    def visit_comment(self, node):
        raise nodes.SkipNode # Not implemented yet

    # Attributes

    def visit_title(self, node):
        set_item_collector(node, 'text')

    def depart_title(self, node):
        node.parent['title'] = node['text']

    def visit_label(self, node):
        raise nodes.SkipNode # Not implemented yet

    def visit_substitution_definition(self, node):
        raise nodes.SkipNode # Not implemented yet

    # Plain text

    def visit_Text(self, node):
        pass

    def depart_Text(self, node):
        text = node.astext()
        if '@' in text:
            text = text.replace('@', '@@')
        if '{' in text:
            text = text.replace('{', '@{')
        if '}' in text:
            text = text.replace('}', '@}')
        node.parent.collect_text(text)


    # Styled text

    def visit_emphasis(self, node):
        set_item_collector(node, 'text')

    def depart_emphasis(self, node):
        text = '@emph{%s}' % node['text']
        node.parent.collect_text(text)

    def visit_strong(self, node):
        set_item_collector(node, 'text')

    def depart_strong(self, node):
        text = '@strong{%s}' % node['text']
        node.parent.collect_text(text)

    def visit_literal(self, node):
        set_item_collector(node, 'text')

    def depart_literal(self, node):
        text = '@code{%s}' % node['text']
        node.parent.collect_text(text)

    # Lists

    def _decorate_list(self, item_list, collect, item_fmt='%s',
                       head=None, foot=None):
        if head is not None:
            collect(head)
        for item in item_list:
            collect(item_fmt % item)
        if foot is not None:
            collect(foot)

    def visit_bullet_list(self, node):
        set_item_list_collector(node, 'list_item')

    def depart_bullet_list(self, node):
        l = node['list_item']
        if self.in_toctree:
            self._decorate_list(node['list_item'], node.parent.collect_text)
        else:
            self._decorate_list(node['list_item'], node.parent.collect_text,
                                '@item\n%s',
                                # FIXME: Should respect the 'bullet' attribute
                                '@itemize @bullet\n', '@end itemize\n')

    def visit_enumerated_list(self, node):
        set_item_list_collector(node, 'list_item')

    def depart_enumerated_list(self, node):
        self._decorate_list(node['list_item'], node.parent.collect_text,
                            '@item\n%s',
                            '@enumerate\n', '@end enumerate\n')

    def visit_definition_list(self, node):
        raise nodes.SkipNode # Not implemented yet

    def depart_definition_list(self, node):
        raise nodes.SkipNode # Not implemented yet

    def visit_definition_list_item(self, node):
        raise nodes.SkipNode # Not implemented yet

    def depart_definition_list_item(self, node):
        pass

    def visit_term(self, node):
        raise nodes.SkipNode # Not implemented yet

    def depart_term(self, node):
        pass

    def visit_definition(self, node):
        raise nodes.SkipNode # Not implemented yet

    def depart_definition(self, node):
        pass

    def visit_field_list(self, node):
        raise nodes.SkipNode # Not implemented yet

    def depart_field_list(self, node):
        pass

    def visit_field(self, node):
        raise nodes.SkipNode # Not implemented yet

    def depart_field(self, node):
        pass

    def visit_field_name(self, node):
        raise nodes.SkipNode # Not implemented yet

    def depart_field_name(self, node):
        pass

    def visit_field_body(self, node):
        raise nodes.SkipNode # Not implemented yet

    def depart_field_body(self, node):
        pass

    def visit_list_item(self, node):
        set_item_list_collector(node, 'text')

    def depart_list_item(self, node):
        text = ''.join(node['text'])
        node.parent.collect_list_item(text)

    def visit_option_list(self, node):
        raise nodes.SkipNode # Not implemented yet

    def depart_option_list(self, node):
        pass

    def visit_option_list_item(self, node):
        pass

    def depart_option_list_item(self, node):
        pass

    def visit_option_group(self, node):
        pass

    def depart_option_group(self, node):
        pass

    def visit_option(self, node):
        pass

    def depart_option(self, node):
        pass

    def visit_option_string(self, node):
        pass
    def depart_option_string(self, node):
        pass

    def visit_option_argument(self, node):
        pass

    def depart_option_argument(self, node):
        pass

    def visit_description(self, node):
        pass
    def depart_description(self, node):
        pass

    # Tables
    def visit_table(self, node):
        set_item_collector(node, 'table')

    def depart_table(self, node):
        node.parent.collect_text(node['table'])

    def visit_tgroup(self, node):
        set_item_list_collector(node, 'colspec')
        set_item_collector(node, 'head_entries')
        set_item_collector(node, 'body_rows')

    def depart_tgroup(self, node):
        header = []
        # The '@multitable {xxx}{xxx}' line
        self._decorate_list(node['colspec'], header.append,
                            '{%s}', '@multitable ', '\n')
        # The '@headitem xxx @tab yyy...' line
        head_entries = node['head_entries']
        if head_entries is not None:
            # Not all tables define titles for the columns... rest parser bug ?
            # FIXME: need a test
            self._decorate_list(head_entries[1:], header.append,
                                ' @tab %s',
                                '@headitem %s' % head_entries[0], '\n')
        header = ''.join(header)
        # The '@item xxx\n @tab yyy\n ...' lines
        body_rows = node['body_rows']
        rows = []
        for r in body_rows:
            self._decorate_list(r[1:], rows.append,
                                '@tab %s\n', '@item %s\n' % r[0])
        footer = '@end multitable\n'
        node.parent.collect_table(header + ''.join(rows) + footer)

    def visit_colspec(self, node):
        pass

    def depart_colspec(self, node):
        node.parent.collect_colspec('x' * node['colwidth'])

    def visit_thead(self, node):
        set_item_collector(node, 'row')

    def depart_thead(self, node):
        node.parent.collect_head_entries(node['row'])

    def visit_tbody(self, node):
        set_item_list_collector(node, 'row')

    def depart_tbody(self, node):
        node.parent.collect_body_rows(node['row'])

    def visit_row(self, node):
        set_item_list_collector(node, 'entry')

    def depart_row(self, node):
        node.parent.collect_row(node['entry'])

    def visit_entry(self, node):
        set_item_list_collector(node, 'text')
        node['par_sep_orig'] = self.paragraph_sep
        self.paragraph_sep = ''

    def depart_entry(self, node):
        node.parent.collect_entry(''.join(node['text']))
        self.paragraph_sep = node['par_sep_orig']

    # References

    def visit_reference(self, node):
        for c in node.children:
            if getattr(c, 'parent', None) is None:
                # Bug sphinx
                node.setup_child(c)
        set_item_collector(node, 'text')

    def depart_reference(self, node):
        anchorname = node.get('anchorname', None)
        refuri = node.get('refuri', None)
        refid = node.get('refid', None)
        text = ''.join(node['text'])
        collect = getattr(node.parent, 'collect_reference', None)
        if collect is not None:
            if not self.in_toctree:
                raise AssertionError('collect_reference is specific to toctree')
            if anchorname is None:
                anchorname = ''
            if refuri is None:
                refuri = ''
            collect((anchorname, refuri, text))
        elif refuri is not None:
            node.parent.collect_text('@uref{%s,%s}' % (refuri, text))
        elif refid is not None:
            # Info format requires that a reference is followed by some
            # punctuation char ('.', ','. ')', etc). Rest is more liberal. To
            # accommodate, we use pxref inside parenthesis.
            node.parent.collect_text('%s (@pxref{%s})' % (text, refid))

    def visit_footnote_reference(self, node):
        raise nodes.SkipNode # Not implemented yet

    def visit_citation_reference(self, node):
        raise nodes.SkipNode # Not implemented yet

    def visit_title_reference(self, node):
        raise nodes.SkipNode # Not implemented yet

    def depart_title_reference(self, node):
        pass

    def visit_target(self, node):
        raise nodes.SkipNode # Not implemented yet

    def depart_target(self, node):
        pass

    def visit_image(self, node):
        raise nodes.SkipNode # Not implemented yet

# Helpers to collect data in parent node

def set_item_collector(node, name):
    node[name] = None
    def set_item(item):
        node[name] = item
    setattr(node, 'collect_' + name, set_item)


def set_item_list_collector(node, name, sep=''):
    node[name] = []
    node[name + '_sep'] = sep
    def append_item(item):
        node[name].append(item)
    setattr(node, 'collect_' + name, append_item)