/brz/remove-bazaar

# 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)