Merge lp:~mitya57/ubuntu/raring/sphinx/1.1.3+dfsg-5ubuntu1 into lp:ubuntu/raring/sphinx

[Dmitry Shachnev]

[Daniel Holbach (dholbach)]

Uploaded. Thanks.

review: Approve

=== modified file '.pc/applied-patches'
--- .pc/applied-patches	2012-11-01 21:39:16 +0000
+++ .pc/applied-patches	2012-11-28 07:12:20 +0000
@@ -9,4 +9,7 @@
 pygments_byte_strings.diff
 fix_shorthandoff.diff
 fix_manpages_generation_with_new_docutils.diff
+test_build_html_rb.diff
+sort_stopwords.diff
 support_python_3.3.diff
+l10n_fixes.diff

=== removed directory '.pc/fix_manpages_generation_with_new_docutils.diff'
=== removed directory '.pc/fix_manpages_generation_with_new_docutils.diff/sphinx'
=== removed directory '.pc/fix_manpages_generation_with_new_docutils.diff/sphinx/writers'
=== removed file '.pc/fix_manpages_generation_with_new_docutils.diff/sphinx/writers/manpage.py'
--- .pc/fix_manpages_generation_with_new_docutils.diff/sphinx/writers/manpage.py	2012-10-22 20:20:35 +0000
+++ .pc/fix_manpages_generation_with_new_docutils.diff/sphinx/writers/manpage.py	1970-01-01 00:00:00 +0000
@@ -1,345 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-    sphinx.writers.manpage
-    ~~~~~~~~~~~~~~~~~~~~~~
-
-    Manual page writer, extended for Sphinx custom nodes.
-
-    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-"""
-
-from docutils import nodes
-try:
-    from docutils.writers.manpage import MACRO_DEF, Writer, \
-         Translator as BaseTranslator
-    has_manpage_writer = True
-except ImportError:
-    # define the classes in any case, sphinx.application needs it
-    Writer = BaseTranslator = object
-    has_manpage_writer = False
-
-from sphinx import addnodes
-from sphinx.locale import admonitionlabels, versionlabels, _
-from sphinx.util.osutil import ustrftime
-
-
-class ManualPageWriter(Writer):
-    def __init__(self, builder):
-        Writer.__init__(self)
-        self.builder = builder
-
-    def translate(self):
-        visitor = ManualPageTranslator(self.builder, self.document)
-        self.visitor = visitor
-        self.document.walkabout(visitor)
-        self.output = visitor.astext()
-
-
-class ManualPageTranslator(BaseTranslator):
-    """
-    Custom translator.
-    """
-
-    def __init__(self, builder, *args, **kwds):
-        BaseTranslator.__init__(self, *args, **kwds)
-        self.builder = builder
-
-        self.in_productionlist = 0
-
-        # first title is the manpage title
-        self.section_level = -1
-
-        # docinfo set by man_pages config value
-        self._docinfo['title'] = self.document.settings.title
-        self._docinfo['subtitle'] = self.document.settings.subtitle
-        if self.document.settings.authors:
-            # don't set it if no author given
-            self._docinfo['author'] = self.document.settings.authors
-        self._docinfo['manual_section'] = self.document.settings.section
-
-        # docinfo set by other config values
-        self._docinfo['title_upper'] = self._docinfo['title'].upper()
-        if builder.config.today:
-            self._docinfo['date'] = builder.config.today
-        else:
-            self._docinfo['date'] = ustrftime(builder.config.today_fmt
-                                              or _('%B %d, %Y'))
-        self._docinfo['copyright'] = builder.config.copyright
-        self._docinfo['version'] = builder.config.version
-        self._docinfo['manual_group'] = builder.config.project
-
-        # since self.append_header() is never called, need to do this here
-        self.body.append(MACRO_DEF)
-
-    # overwritten -- added quotes around all .TH arguments
-    def header(self):
-        tmpl = (".TH \"%(title_upper)s\" \"%(manual_section)s\""
-                " \"%(date)s\" \"%(version)s\" \"%(manual_group)s\"\n"
-                ".SH NAME\n"
-                "%(title)s \- %(subtitle)s\n")
-        return tmpl % self._docinfo
-
-    def visit_start_of_file(self, node):
-        pass
-    def depart_start_of_file(self, node):
-        pass
-
-    def visit_desc(self, node):
-        self.visit_definition_list(node)
-    def depart_desc(self, node):
-        self.depart_definition_list(node)
-
-    def visit_desc_signature(self, node):
-        self.visit_definition_list_item(node)
-        self.visit_term(node)
-    def depart_desc_signature(self, node):
-        self.depart_term(node)
-
-    def visit_desc_addname(self, node):
-        pass
-    def depart_desc_addname(self, node):
-        pass
-
-    def visit_desc_type(self, node):
-        pass
-    def depart_desc_type(self, node):
-        pass
-
-    def visit_desc_returns(self, node):
-        self.body.append(' -> ')
-    def depart_desc_returns(self, node):
-        pass
-
-    def visit_desc_name(self, node):
-        pass
-    def depart_desc_name(self, node):
-        pass
-
-    def visit_desc_parameterlist(self, node):
-        self.body.append('(')
-        self.first_param = 1
-    def depart_desc_parameterlist(self, node):
-        self.body.append(')')
-
-    def visit_desc_parameter(self, node):
-        if not self.first_param:
-            self.body.append(', ')
-        else:
-            self.first_param = 0
-    def depart_desc_parameter(self, node):
-        pass
-
-    def visit_desc_optional(self, node):
-        self.body.append('[')
-    def depart_desc_optional(self, node):
-        self.body.append(']')
-
-    def visit_desc_annotation(self, node):
-        pass
-    def depart_desc_annotation(self, node):
-        pass
-
-    def visit_desc_content(self, node):
-        self.visit_definition(node)
-    def depart_desc_content(self, node):
-        self.depart_definition(node)
-
-    def visit_refcount(self, node):
-        self.body.append(self.defs['emphasis'][0])
-    def depart_refcount(self, node):
-        self.body.append(self.defs['emphasis'][1])
-
-    def visit_versionmodified(self, node):
-        self.visit_paragraph(node)
-        text = versionlabels[node['type']] % node['version']
-        if len(node):
-            text += ': '
-        else:
-            text += '.'
-        self.body.append(text)
-    def depart_versionmodified(self, node):
-        self.depart_paragraph(node)
-
-    def visit_termsep(self, node):
-        self.body.append(', ')
-        raise nodes.SkipNode
-
-    # overwritten -- we don't want source comments to show up
-    def visit_comment(self, node):
-        raise nodes.SkipNode
-
-    # overwritten -- added ensure_eol()
-    def visit_footnote(self, node):
-        self.ensure_eol()
-        BaseTranslator.visit_footnote(self, node)
-
-    # overwritten -- handle footnotes rubric
-    def visit_rubric(self, node):
-        self.ensure_eol()
-        if len(node.children) == 1:
-            rubtitle = node.children[0].astext()
-            if rubtitle in ('Footnotes', _('Footnotes')):
-                self.body.append('.SH ' + self.deunicode(rubtitle).upper() +
-                                 '\n')
-                raise nodes.SkipNode
-        else:
-            self.body.append('.sp\n')
-    def depart_rubric(self, node):
-        pass
-
-    def visit_seealso(self, node):
-        self.visit_admonition(node)
-    def depart_seealso(self, node):
-        self.depart_admonition(node)
-
-    # overwritten -- use our own label translations
-    def visit_admonition(self, node, name=None):
-        if name:
-            self.body.append('.IP %s\n' %
-                             self.deunicode(admonitionlabels.get(name, name)))
-
-    def visit_productionlist(self, node):
-        self.ensure_eol()
-        names = []
-        self.in_productionlist += 1
-        self.body.append('.sp\n.nf\n')
-        for production in node:
-            names.append(production['tokenname'])
-        maxlen = max(len(name) for name in names)
-        for production in node:
-            if production['tokenname']:
-                lastname = production['tokenname'].ljust(maxlen)
-                self.body.append(self.defs['strong'][0])
-                self.body.append(self.deunicode(lastname))
-                self.body.append(self.defs['strong'][1])
-                self.body.append(' ::= ')
-            else:
-                self.body.append('%s     ' % (' '*len(lastname)))
-            production.walkabout(self)
-            self.body.append('\n')
-        self.body.append('\n.fi\n')
-        self.in_productionlist -= 1
-        raise nodes.SkipNode
-
-    def visit_production(self, node):
-        pass
-    def depart_production(self, node):
-        pass
-
-    # overwritten -- don't emit a warning for images
-    def visit_image(self, node):
-        if 'alt' in node.attributes:
-            self.body.append(_('[image: %s]') % node['alt'] + '\n')
-        self.body.append(_('[image]') + '\n')
-        raise nodes.SkipNode
-
-    # overwritten -- don't visit inner marked up nodes
-    def visit_reference(self, node):
-        self.body.append(self.defs['reference'][0])
-        self.body.append(node.astext())
-        self.body.append(self.defs['reference'][1])
-
-        uri = node.get('refuri', '')
-        if uri.startswith('mailto:') or uri.startswith('http:') or \
-                 uri.startswith('https:') or uri.startswith('ftp:'):
-            # if configured, put the URL after the link
-            if self.builder.config.man_show_urls and \
-                   node.astext() != uri:
-                if uri.startswith('mailto:'):
-                    uri = uri[7:]
-                self.body.extend([
-                    ' <',
-                    self.defs['strong'][0], uri, self.defs['strong'][1],
-                    '>'])
-        raise nodes.SkipNode
-
-    def visit_centered(self, node):
-        self.ensure_eol()
-        self.body.append('.sp\n.ce\n')
-    def depart_centered(self, node):
-        self.body.append('\n.ce 0\n')
-
-    def visit_compact_paragraph(self, node):
-        pass
-    def depart_compact_paragraph(self, node):
-        pass
-
-    def visit_highlightlang(self, node):
-        pass
-    def depart_highlightlang(self, node):
-        pass
-
-    def visit_download_reference(self, node):
-        pass
-    def depart_download_reference(self, node):
-        pass
-
-    def visit_toctree(self, node):
-        raise nodes.SkipNode
-
-    def visit_index(self, node):
-        raise nodes.SkipNode
-
-    def visit_tabular_col_spec(self, node):
-        raise nodes.SkipNode
-
-    def visit_glossary(self, node):
-        pass
-    def depart_glossary(self, node):
-        pass
-
-    def visit_acks(self, node):
-        self.ensure_eol()
-        self.body.append(', '.join(n.astext()
-                                   for n in node.children[0].children) + '.')
-        self.body.append('\n')
-        raise nodes.SkipNode
-
-    def visit_hlist(self, node):
-        self.visit_bullet_list(node)
-    def depart_hlist(self, node):
-        self.depart_bullet_list(node)
-
-    def visit_hlistcol(self, node):
-        pass
-    def depart_hlistcol(self, node):
-        pass
-
-    def visit_literal_emphasis(self, node):
-        return self.visit_emphasis(node)
-    def depart_literal_emphasis(self, node):
-        return self.depart_emphasis(node)
-
-    def visit_abbreviation(self, node):
-        pass
-    def depart_abbreviation(self, node):
-        pass
-
-    # overwritten: handle section titles better than in 0.6 release
-    def visit_title(self, node):
-        if isinstance(node.parent, addnodes.seealso):
-            self.body.append('.IP "')
-            return
-        elif isinstance(node.parent, nodes.section):
-            if self.section_level == 0:
-                # skip the document title
-                raise nodes.SkipNode
-            elif self.section_level == 1:
-                self.body.append('.SH %s\n' %
-                                 self.deunicode(node.astext().upper()))
-                raise nodes.SkipNode
-        return BaseTranslator.visit_title(self, node)
-    def depart_title(self, node):
-        if isinstance(node.parent, addnodes.seealso):
-            self.body.append('"\n')
-            return
-        return BaseTranslator.depart_title(self, node)
-
-    def visit_raw(self, node):
-        if 'manpage' in node.get('format', '').split():
-            self.body.append(node.astext())
-        raise nodes.SkipNode
-
-    def unknown_visit(self, node):
-        raise NotImplementedError('Unknown node: ' + node.__class__.__name__)

=== added directory '.pc/l10n_fixes.diff'
=== added directory '.pc/l10n_fixes.diff/sphinx'
=== added file '.pc/l10n_fixes.diff/sphinx/environment.py'
--- .pc/l10n_fixes.diff/sphinx/environment.py	1970-01-01 00:00:00 +0000
+++ .pc/l10n_fixes.diff/sphinx/environment.py	2012-11-28 07:12:20 +0000
@@ -0,0 +1,1762 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.environment
+    ~~~~~~~~~~~~~~~~~~
+
+    Global creation environment.
+
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import re
+import os
+import sys
+import time
+import types
+import codecs
+import imghdr
+import string
+import unicodedata
+import cPickle as pickle
+from os import path
+from glob import glob
+from itertools import izip, groupby
+
+from docutils import nodes
+from docutils.io import FileInput, NullOutput
+from docutils.core import Publisher
+from docutils.utils import Reporter, relative_path, new_document, \
+     get_source_line
+from docutils.readers import standalone
+from docutils.parsers.rst import roles, directives, Parser as RSTParser
+from docutils.parsers.rst.languages import en as english
+from docutils.parsers.rst.directives.html import MetaBody
+from docutils.writers import UnfilteredWriter
+from docutils.transforms import Transform
+from docutils.transforms.parts import ContentsFilter
+
+from sphinx import addnodes
+from sphinx.util import url_re, get_matching_docs, docname_join, split_into, \
+     FilenameUniqDict
+from sphinx.util.nodes import clean_astext, make_refnode, extract_messages, \
+     WarningStream
+from sphinx.util.osutil import movefile, SEP, ustrftime, find_catalog
+from sphinx.util.matching import compile_matchers
+from sphinx.util.pycompat import all, class_types
+from sphinx.util.websupport import is_commentable
+from sphinx.errors import SphinxError, ExtensionError
+from sphinx.locale import _, init as init_locale
+from sphinx.versioning import add_uids, merge_doctrees
+
+fs_encoding = sys.getfilesystemencoding() or sys.getdefaultencoding()
+
+orig_role_function = roles.role
+orig_directive_function = directives.directive
+
+class ElementLookupError(Exception): pass
+
+
+default_settings = {
+    'embed_stylesheet': False,
+    'cloak_email_addresses': True,
+    'pep_base_url': 'http://www.python.org/dev/peps/',
+    'rfc_base_url': 'http://tools.ietf.org/html/',
+    'input_encoding': 'utf-8-sig',
+    'doctitle_xform': False,
+    'sectsubtitle_xform': False,
+    'halt_level': 5,
+}
+
+# This is increased every time an environment attribute is added
+# or changed to properly invalidate pickle files.
+ENV_VERSION = 41
+
+
+default_substitutions = set([
+    'version',
+    'release',
+    'today',
+])
+
+dummy_reporter = Reporter('', 4, 4)
+
+versioning_conditions = {
+    'none': False,
+    'text': nodes.TextElement,
+    'commentable': is_commentable,
+}
+
+
+class NoUri(Exception):
+    """Raised by get_relative_uri if there is no URI available."""
+    pass
+
+
+class DefaultSubstitutions(Transform):
+    """
+    Replace some substitutions if they aren't defined in the document.
+    """
+    # run before the default Substitutions
+    default_priority = 210
+
+    def apply(self):
+        config = self.document.settings.env.config
+        # only handle those not otherwise defined in the document
+        to_handle = default_substitutions - set(self.document.substitution_defs)
+        for ref in self.document.traverse(nodes.substitution_reference):
+            refname = ref['refname']
+            if refname in to_handle:
+                text = config[refname]
+                if refname == 'today' and not text:
+                    # special handling: can also specify a strftime format
+                    text = ustrftime(config.today_fmt or _('%B %d, %Y'))
+                ref.replace_self(nodes.Text(text, text))
+
+
+class MoveModuleTargets(Transform):
+    """
+    Move module targets that are the first thing in a section to the section
+    title.
+
+    XXX Python specific
+    """
+    default_priority = 210
+
+    def apply(self):
+        for node in self.document.traverse(nodes.target):
+            if not node['ids']:
+                continue
+            if (node.has_key('ismod') and
+                node.parent.__class__ is nodes.section and
+                # index 0 is the section title node
+                node.parent.index(node) == 1):
+                node.parent['ids'][0:0] = node['ids']
+                node.parent.remove(node)
+
+
+class HandleCodeBlocks(Transform):
+    """
+    Several code block related transformations.
+    """
+    default_priority = 210
+
+    def apply(self):
+        # move doctest blocks out of blockquotes
+        for node in self.document.traverse(nodes.block_quote):
+            if all(isinstance(child, nodes.doctest_block) for child
+                     in node.children):
+                node.replace_self(node.children)
+        # combine successive doctest blocks
+        #for node in self.document.traverse(nodes.doctest_block):
+        #    if node not in node.parent.children:
+        #        continue
+        #    parindex = node.parent.index(node)
+        #    while len(node.parent) > parindex+1 and \
+        #            isinstance(node.parent[parindex+1], nodes.doctest_block):
+        #        node[0] = nodes.Text(node[0] + '\n\n' +
+        #                             node.parent[parindex+1][0])
+        #        del node.parent[parindex+1]
+
+
+class SortIds(Transform):
+    """
+    Sort secion IDs so that the "id[0-9]+" one comes last.
+    """
+    default_priority = 261
+
+    def apply(self):
+        for node in self.document.traverse(nodes.section):
+            if len(node['ids']) > 1 and node['ids'][0].startswith('id'):
+                node['ids'] = node['ids'][1:] + [node['ids'][0]]
+
+
+class CitationReferences(Transform):
+    """
+    Replace citation references by pending_xref nodes before the default
+    docutils transform tries to resolve them.
+    """
+    default_priority = 619
+
+    def apply(self):
+        for citnode in self.document.traverse(nodes.citation_reference):
+            cittext = citnode.astext()
+            refnode = addnodes.pending_xref(cittext, reftype='citation',
+                                            reftarget=cittext, refwarn=True)
+            refnode.line = citnode.line or citnode.parent.line
+            refnode += nodes.Text('[' + cittext + ']')
+            citnode.parent.replace(citnode, refnode)
+
+
+class Locale(Transform):
+    """
+    Replace translatable nodes with their translated doctree.
+    """
+    default_priority = 0
+    def apply(self):
+        env = self.document.settings.env
+        settings, source = self.document.settings, self.document['source']
+        # XXX check if this is reliable
+        assert source.startswith(env.srcdir)
+        docname = path.splitext(relative_path(env.srcdir, source))[0]
+        textdomain = find_catalog(docname,
+                                  self.document.settings.gettext_compact)
+
+        # fetch translations
+        dirs = [path.join(env.srcdir, directory)
+                for directory in env.config.locale_dirs]
+        catalog, has_catalog = init_locale(dirs, env.config.language,
+                                           textdomain)
+        if not has_catalog:
+            return
+
+        parser = RSTParser()
+
+        for node, msg in extract_messages(self.document):
+            patch = new_document(source, settings)
+            msgstr = catalog.gettext(msg)
+            # XXX add marker to untranslated parts
+            if not msgstr or msgstr == msg: # as-of-yet untranslated
+                continue
+            parser.parse(msgstr, patch)
+            patch = patch[0]
+            # XXX doctest and other block markup
+            if not isinstance(patch, nodes.paragraph):
+                continue # skip for now
+            for child in patch.children: # update leaves
+                child.parent = node
+            node.children = patch.children
+
+
+class SphinxStandaloneReader(standalone.Reader):
+    """
+    Add our own transforms.
+    """
+    transforms = [Locale, CitationReferences, DefaultSubstitutions,
+                  MoveModuleTargets, HandleCodeBlocks, SortIds]
+
+    def get_transforms(self):
+        return standalone.Reader.get_transforms(self) + self.transforms
+
+
+class SphinxDummyWriter(UnfilteredWriter):
+    supported = ('html',)  # needed to keep "meta" nodes
+
+    def translate(self):
+        pass
+
+
+class SphinxContentsFilter(ContentsFilter):
+    """
+    Used with BuildEnvironment.add_toc_from() to discard cross-file links
+    within table-of-contents link nodes.
+    """
+    def visit_pending_xref(self, node):
+        text = node.astext()
+        self.parent.append(nodes.literal(text, text))
+        raise nodes.SkipNode
+
+    def visit_image(self, node):
+        raise nodes.SkipNode
+
+
+class BuildEnvironment:
+    """
+    The environment in which the ReST files are translated.
+    Stores an inventory of cross-file targets and provides doctree
+    transformations to resolve links to them.
+    """
+
+    # --------- ENVIRONMENT PERSISTENCE ----------------------------------------
+
+    @staticmethod
+    def frompickle(config, filename):
+        picklefile = open(filename, 'rb')
+        try:
+            env = pickle.load(picklefile)
+        finally:
+            picklefile.close()
+        if env.version != ENV_VERSION:
+            raise IOError('env version not current')
+        env.config.values = config.values
+        return env
+
+    def topickle(self, filename):
+        # remove unpicklable attributes
+        warnfunc = self._warnfunc
+        self.set_warnfunc(None)
+        values = self.config.values
+        del self.config.values
+        domains = self.domains
+        del self.domains
+        # first write to a temporary file, so that if dumping fails,
+        # the existing environment won't be overwritten
+        picklefile = open(filename + '.tmp', 'wb')
+        # remove potentially pickling-problematic values from config
+        for key, val in vars(self.config).items():
+            if key.startswith('_') or \
+                   isinstance(val, types.ModuleType) or \
+                   isinstance(val, types.FunctionType) or \
+                   isinstance(val, class_types):
+                del self.config[key]
+        try:
+            pickle.dump(self, picklefile, pickle.HIGHEST_PROTOCOL)
+        finally:
+            picklefile.close()
+        movefile(filename + '.tmp', filename)
+        # reset attributes
+        self.domains = domains
+        self.config.values = values
+        self.set_warnfunc(warnfunc)
+
+    # --------- ENVIRONMENT INITIALIZATION -------------------------------------
+
+    def __init__(self, srcdir, doctreedir, config):
+        self.doctreedir = doctreedir
+        self.srcdir = srcdir
+        self.config = config
+
+        # the method of doctree versioning; see set_versioning_method
+        self.versioning_condition = None
+
+        # the application object; only set while update() runs
+        self.app = None
+
+        # all the registered domains, set by the application
+        self.domains = {}
+
+        # the docutils settings for building
+        self.settings = default_settings.copy()
+        self.settings['env'] = self
+
+        # the function to write warning messages with
+        self._warnfunc = None
+
+        # this is to invalidate old pickles
+        self.version = ENV_VERSION
+
+        # make this a set for faster testing
+        self._nitpick_ignore = set(self.config.nitpick_ignore)
+
+        # All "docnames" here are /-separated and relative and exclude
+        # the source suffix.
+
+        self.found_docs = set()     # contains all existing docnames
+        self.all_docs = {}          # docname -> mtime at the time of build
+                                    # contains all built docnames
+        self.dependencies = {}      # docname -> set of dependent file
+                                    # names, relative to documentation root
+        self.reread_always = set()  # docnames to re-read unconditionally on
+                                    # next build
+
+        # File metadata
+        self.metadata = {}          # docname -> dict of metadata items
+
+        # TOC inventory
+        self.titles = {}            # docname -> title node
+        self.longtitles = {}        # docname -> title node; only different if
+                                    # set differently with title directive
+        self.tocs = {}              # docname -> table of contents nodetree
+        self.toc_num_entries = {}   # docname -> number of real entries
+        # used to determine when to show the TOC
+        # in a sidebar (don't show if it's only one item)
+        self.toc_secnumbers = {}    # docname -> dict of sectionid -> number
+
+        self.toctree_includes = {}  # docname -> list of toctree includefiles
+        self.files_to_rebuild = {}  # docname -> set of files
+                                    # (containing its TOCs) to rebuild too
+        self.glob_toctrees = set()  # docnames that have :glob: toctrees
+        self.numbered_toctrees = set() # docnames that have :numbered: toctrees
+
+        # domain-specific inventories, here to be pickled
+        self.domaindata = {}        # domainname -> domain-specific dict
+
+        # Other inventories
+        self.citations = {}         # citation name -> docname, labelid
+        self.indexentries = {}      # docname -> list of
+                                    # (type, string, target, aliasname)
+        self.versionchanges = {}    # version -> list of (type, docname,
+                                    # lineno, module, descname, content)
+
+        # these map absolute path -> (docnames, unique filename)
+        self.images = FilenameUniqDict()
+        self.dlfiles = FilenameUniqDict()
+
+        # temporary data storage while reading a document
+        self.temp_data = {}
+
+    def set_warnfunc(self, func):
+        self._warnfunc = func
+        self.settings['warning_stream'] = WarningStream(func)
+
+    def set_versioning_method(self, method):
+        """This sets the doctree versioning method for this environment.
+
+        Versioning methods are a builder property; only builders with the same
+        versioning method can share the same doctree directory.  Therefore, we
+        raise an exception if the user tries to use an environment with an
+        incompatible versioning method.
+        """
+        if method not in versioning_conditions:
+            raise ValueError('invalid versioning method: %r' % method)
+        condition = versioning_conditions[method]
+        if self.versioning_condition not in (None, condition):
+            raise SphinxError('This environment is incompatible with the '
+                              'selected builder, please choose another '
+                              'doctree directory.')
+        self.versioning_condition = condition
+
+    def warn(self, docname, msg, lineno=None):
+        # strange argument order is due to backwards compatibility
+        self._warnfunc(msg, (docname, lineno))
+
+    def warn_node(self, msg, node):
+        self._warnfunc(msg, '%s:%s' % get_source_line(node))
+
+    def clear_doc(self, docname):
+        """Remove all traces of a source file in the inventory."""
+        if docname in self.all_docs:
+            self.all_docs.pop(docname, None)
+            self.reread_always.discard(docname)
+            self.metadata.pop(docname, None)
+            self.dependencies.pop(docname, None)
+            self.titles.pop(docname, None)
+            self.longtitles.pop(docname, None)
+            self.tocs.pop(docname, None)
+            self.toc_secnumbers.pop(docname, None)
+            self.toc_num_entries.pop(docname, None)
+            self.toctree_includes.pop(docname, None)
+            self.indexentries.pop(docname, None)
+            self.glob_toctrees.discard(docname)
+            self.numbered_toctrees.discard(docname)
+            self.images.purge_doc(docname)
+            self.dlfiles.purge_doc(docname)
+
+            for subfn, fnset in self.files_to_rebuild.items():
+                fnset.discard(docname)
+                if not fnset:
+                    del self.files_to_rebuild[subfn]
+            for key, (fn, _) in self.citations.items():
+                if fn == docname:
+                    del self.citations[key]
+            for version, changes in self.versionchanges.items():
+                new = [change for change in changes if change[1] != docname]
+                changes[:] = new
+
+        for domain in self.domains.values():
+            domain.clear_doc(docname)
+
+    def doc2path(self, docname, base=True, suffix=None):
+        """Return the filename for the document name.
+
+        If *base* is True, return absolute path under self.srcdir.
+        If *base* is None, return relative path to self.srcdir.
+        If *base* is a path string, return absolute path under that.
+        If *suffix* is not None, add it instead of config.source_suffix.
+        """
+        docname = docname.replace(SEP, path.sep)
+        suffix = suffix or self.config.source_suffix
+        if base is True:
+            return path.join(self.srcdir, docname) + suffix
+        elif base is None:
+            return docname + suffix
+        else:
+            return path.join(base, docname) + suffix
+
+    def relfn2path(self, filename, docname=None):
+        """Return paths to a file referenced from a document, relative to
+        documentation root and absolute.
+
+        Absolute filenames are relative to the source dir, while relative
+        filenames are relative to the dir of the containing document.
+        """
+        if filename.startswith('/') or filename.startswith(os.sep):
+            rel_fn = filename[1:]
+        else:
+            docdir = path.dirname(self.doc2path(docname or self.docname,
+                                                base=None))
+            rel_fn = path.join(docdir, filename)
+        try:
+            return rel_fn, path.join(self.srcdir, rel_fn)
+        except UnicodeDecodeError:
+            # the source directory is a bytestring with non-ASCII characters;
+            # let's try to encode the rel_fn in the file system encoding
+            enc_rel_fn = rel_fn.encode(sys.getfilesystemencoding())
+            return rel_fn, path.join(self.srcdir, enc_rel_fn)
+
+    def find_files(self, config):
+        """Find all source files in the source dir and put them in
+        self.found_docs.
+        """
+        matchers = compile_matchers(
+            config.exclude_patterns[:] +
+            config.exclude_trees +
+            [d + config.source_suffix for d in config.unused_docs] +
+            ['**/' + d for d in config.exclude_dirnames] +
+            ['**/_sources', '.#*']
+        )
+        self.found_docs = set(get_matching_docs(
+            self.srcdir, config.source_suffix, exclude_matchers=matchers))
+
+    def get_outdated_files(self, config_changed):
+        """Return (added, changed, removed) sets."""
+        # clear all files no longer present
+        removed = set(self.all_docs) - self.found_docs
+
+        added = set()
+        changed = set()
+
+        if config_changed:
+            # config values affect e.g. substitutions
+            added = self.found_docs
+        else:
+            for docname in self.found_docs:
+                if docname not in self.all_docs:
+                    added.add(docname)
+                    continue
+                # if the doctree file is not there, rebuild
+                if not path.isfile(self.doc2path(docname, self.doctreedir,
+                                                 '.doctree')):
+                    changed.add(docname)
+                    continue
+                # check the "reread always" list
+                if docname in self.reread_always:
+                    changed.add(docname)
+                    continue
+                # check the mtime of the document
+                mtime = self.all_docs[docname]
+                newmtime = path.getmtime(self.doc2path(docname))
+                if newmtime > mtime:
+                    changed.add(docname)
+                    continue
+                # finally, check the mtime of dependencies
+                for dep in self.dependencies.get(docname, ()):
+                    try:
+                        # this will do the right thing when dep is absolute too
+                        deppath = path.join(self.srcdir, dep)
+                        if not path.isfile(deppath):
+                            changed.add(docname)
+                            break
+                        depmtime = path.getmtime(deppath)
+                        if depmtime > mtime:
+                            changed.add(docname)
+                            break
+                    except EnvironmentError:
+                        # give it another chance
+                        changed.add(docname)
+                        break
+
+        return added, changed, removed
+
+    def update(self, config, srcdir, doctreedir, app=None):
+        """(Re-)read all files new or changed since last update.
+
+        Returns a summary, the total count of documents to reread and an
+        iterator that yields docnames as it processes them.  Store all
+        environment docnames in the canonical format (ie using SEP as a
+        separator in place of os.path.sep).
+        """
+        config_changed = False
+        if self.config is None:
+            msg = '[new config] '
+            config_changed = True
+        else:
+            # check if a config value was changed that affects how
+            # doctrees are read
+            for key, descr in config.values.iteritems():
+                if descr[1] != 'env':
+                    continue
+                if self.config[key] != config[key]:
+                    msg = '[config changed] '
+                    config_changed = True
+                    break
+            else:
+                msg = ''
+            # this value is not covered by the above loop because it is handled
+            # specially by the config class
+            if self.config.extensions != config.extensions:
+                msg = '[extensions changed] '
+                config_changed = True
+        # the source and doctree directories may have been relocated
+        self.srcdir = srcdir
+        self.doctreedir = doctreedir
+        self.find_files(config)
+        self.config = config
+
+        added, changed, removed = self.get_outdated_files(config_changed)
+
+        # allow user intervention as well
+        for docs in app.emit('env-get-outdated', self, added, changed, removed):
+            changed.update(set(docs) & self.found_docs)
+
+        # if files were added or removed, all documents with globbed toctrees
+        # must be reread
+        if added or removed:
+            # ... but not those that already were removed
+            changed.update(self.glob_toctrees & self.found_docs)
+
+        msg += '%s added, %s changed, %s removed' % (len(added), len(changed),
+                                                     len(removed))
+
+        def update_generator():
+            self.app = app
+
+            # clear all files no longer present
+            for docname in removed:
+                if app:
+                    app.emit('env-purge-doc', self, docname)
+                self.clear_doc(docname)
+
+            # read all new and changed files
+            for docname in sorted(added | changed):
+                yield docname
+                self.read_doc(docname, app=app)
+
+            if config.master_doc not in self.all_docs:
+                self.warn(None, 'master file %s not found' %
+                          self.doc2path(config.master_doc))
+
+            self.app = None
+            if app:
+                app.emit('env-updated', self)
+
+        return msg, len(added | changed), update_generator()
+
+    def check_dependents(self, already):
+        to_rewrite = self.assign_section_numbers()
+        for docname in to_rewrite:
+            if docname not in already:
+                yield docname
+
+    # --------- SINGLE FILE READING --------------------------------------------
+
+    def warn_and_replace(self, error):
+        """Custom decoding error handler that warns and replaces."""
+        linestart = error.object.rfind('\n', 0, error.start)
+        lineend = error.object.find('\n', error.start)
+        if lineend == -1: lineend = len(error.object)
+        lineno = error.object.count('\n', 0, error.start) + 1
+        self.warn(self.docname, 'undecodable source characters, '
+                  'replacing with "?": %r' %
+                  (error.object[linestart+1:error.start] + '>>>' +
+                   error.object[error.start:error.end] + '<<<' +
+                   error.object[error.end:lineend]), lineno)
+        return (u'?', error.end)
+
+    def lookup_domain_element(self, type, name):
+        """Lookup a markup element (directive or role), given its name which can
+        be a full name (with domain).
+        """
+        name = name.lower()
+        # explicit domain given?
+        if ':' in name:
+            domain_name, name = name.split(':', 1)
+            if domain_name in self.domains:
+                domain = self.domains[domain_name]
+                element = getattr(domain, type)(name)
+                if element is not None:
+                    return element, []
+        # else look in the default domain
+        else:
+            def_domain = self.temp_data.get('default_domain')
+            if def_domain is not None:
+                element = getattr(def_domain, type)(name)
+                if element is not None:
+                    return element, []
+        # always look in the std domain
+        element = getattr(self.domains['std'], type)(name)
+        if element is not None:
+            return element, []
+        raise ElementLookupError
+
+    def patch_lookup_functions(self):
+        """Monkey-patch directive and role dispatch, so that domain-specific
+        markup takes precedence.
+        """
+        def directive(name, lang_module, document):
+            try:
+                return self.lookup_domain_element('directive', name)
+            except ElementLookupError:
+                return orig_directive_function(name, lang_module, document)
+
+        def role(name, lang_module, lineno, reporter):
+            try:
+                return self.lookup_domain_element('role', name)
+            except ElementLookupError:
+                return orig_role_function(name, lang_module, lineno, reporter)
+
+        directives.directive = directive
+        roles.role = role
+
+    def read_doc(self, docname, src_path=None, save_parsed=True, app=None):
+        """Parse a file and add/update inventory entries for the doctree.
+
+        If srcpath is given, read from a different source file.
+        """
+        # remove all inventory entries for that file
+        if app:
+            app.emit('env-purge-doc', self, docname)
+
+        self.clear_doc(docname)
+
+        if src_path is None:
+            src_path = self.doc2path(docname)
+
+        self.temp_data['docname'] = docname
+        # defaults to the global default, but can be re-set in a document
+        self.temp_data['default_domain'] = \
+            self.domains.get(self.config.primary_domain)
+
+        self.settings['input_encoding'] = self.config.source_encoding
+        self.settings['trim_footnote_reference_space'] = \
+            self.config.trim_footnote_reference_space
+        self.settings['gettext_compact'] = self.config.gettext_compact
+
+        self.patch_lookup_functions()
+
+        if self.config.default_role:
+            role_fn, messages = roles.role(self.config.default_role, english,
+                                           0, dummy_reporter)
+            if role_fn:
+                roles._roles[''] = role_fn
+            else:
+                self.warn(docname, 'default role %s not found' %
+                          self.config.default_role)
+
+        codecs.register_error('sphinx', self.warn_and_replace)
+
+        class SphinxSourceClass(FileInput):
+            def __init__(self_, *args, **kwds):
+                # don't call sys.exit() on IOErrors
+                kwds['handle_io_errors'] = False
+                FileInput.__init__(self_, *args, **kwds)
+
+            def decode(self_, data):
+                if isinstance(data, unicode):
+                    return data
+                return data.decode(self_.encoding, 'sphinx')
+
+            def read(self_):
+                data = FileInput.read(self_)
+                if app:
+                    arg = [data]
+                    app.emit('source-read', docname, arg)
+                    data = arg[0]
+                if self.config.rst_epilog:
+                    data = data + '\n' + self.config.rst_epilog + '\n'
+                if self.config.rst_prolog:
+                    data = self.config.rst_prolog + '\n' + data
+                return data
+
+        # publish manually
+        pub = Publisher(reader=SphinxStandaloneReader(),
+                        writer=SphinxDummyWriter(),
+                        source_class=SphinxSourceClass,
+                        destination_class=NullOutput)
+        pub.set_components(None, 'restructuredtext', None)
+        pub.process_programmatic_settings(None, self.settings, None)
+        pub.set_source(None, src_path.encode(fs_encoding))
+        pub.set_destination(None, None)
+        try:
+            pub.publish()
+            doctree = pub.document
+        except UnicodeError, err:
+            raise SphinxError(str(err))
+
+        # post-processing
+        self.filter_messages(doctree)
+        self.process_dependencies(docname, doctree)
+        self.process_images(docname, doctree)
+        self.process_downloads(docname, doctree)
+        self.process_metadata(docname, doctree)
+        self.process_refonly_bullet_lists(docname, doctree)
+        self.create_title_from(docname, doctree)
+        self.note_indexentries_from(docname, doctree)
+        self.note_citations_from(docname, doctree)
+        self.build_toc_from(docname, doctree)
+        for domain in self.domains.itervalues():
+            domain.process_doc(self, docname, doctree)
+
+        # allow extension-specific post-processing
+        if app:
+            app.emit('doctree-read', doctree)
+
+        # store time of build, for outdated files detection
+        self.all_docs[docname] = time.time()
+
+        if self.versioning_condition:
+            # get old doctree
+            try:
+                f = open(self.doc2path(docname,
+                                       self.doctreedir, '.doctree'), 'rb')
+                try:
+                    old_doctree = pickle.load(f)
+                finally:
+                    f.close()
+            except EnvironmentError:
+                old_doctree = None
+
+            # add uids for versioning
+            if old_doctree is None:
+                list(add_uids(doctree, self.versioning_condition))
+            else:
+                list(merge_doctrees(
+                    old_doctree, doctree, self.versioning_condition))
+
+        # make it picklable
+        doctree.reporter = None
+        doctree.transformer = None
+        doctree.settings.warning_stream = None
+        doctree.settings.env = None
+        doctree.settings.record_dependencies = None
+        for metanode in doctree.traverse(MetaBody.meta):
+            # docutils' meta nodes aren't picklable because the class is nested
+            metanode.__class__ = addnodes.meta
+
+        # cleanup
+        self.temp_data.clear()
+
+        if save_parsed:
+            # save the parsed doctree
+            doctree_filename = self.doc2path(docname, self.doctreedir,
+                                             '.doctree')
+            dirname = path.dirname(doctree_filename)
+            if not path.isdir(dirname):
+                os.makedirs(dirname)
+            f = open(doctree_filename, 'wb')
+            try:
+                pickle.dump(doctree, f, pickle.HIGHEST_PROTOCOL)
+            finally:
+                f.close()
+        else:
+            return doctree
+
+    # utilities to use while reading a document
+
+    @property
+    def docname(self):
+        """Backwards compatible alias."""
+        return self.temp_data['docname']
+
+    @property
+    def currmodule(self):
+        """Backwards compatible alias."""
+        return self.temp_data.get('py:module')
+
+    @property
+    def currclass(self):
+        """Backwards compatible alias."""
+        return self.temp_data.get('py:class')
+
+    def new_serialno(self, category=''):
+        """Return a serial number, e.g. for index entry targets."""
+        key = category + 'serialno'
+        cur = self.temp_data.get(key, 0)
+        self.temp_data[key] = cur + 1
+        return cur
+
+    def note_dependency(self, filename):
+        self.dependencies.setdefault(self.docname, set()).add(filename)
+
+    def note_reread(self):
+        self.reread_always.add(self.docname)
+
+    def note_versionchange(self, type, version, node, lineno):
+        self.versionchanges.setdefault(version, []).append(
+            (type, self.temp_data['docname'], lineno,
+             self.temp_data.get('py:module'),
+             self.temp_data.get('object'), node.astext()))
+
+    # post-processing of read doctrees
+
+    def filter_messages(self, doctree):
+        """Filter system messages from a doctree."""
+        filterlevel = self.config.keep_warnings and 2 or 5
+        for node in doctree.traverse(nodes.system_message):
+            if node['level'] < filterlevel:
+                node.parent.remove(node)
+
+
+    def process_dependencies(self, docname, doctree):
+        """Process docutils-generated dependency info."""
+        cwd = os.getcwd()
+        frompath = path.join(path.normpath(self.srcdir), 'dummy')
+        deps = doctree.settings.record_dependencies
+        if not deps:
+            return
+        for dep in deps.list:
+            # the dependency path is relative to the working dir, so get
+            # one relative to the srcdir
+            relpath = relative_path(frompath,
+                                    path.normpath(path.join(cwd, dep)))
+            self.dependencies.setdefault(docname, set()).add(relpath)
+
+    def process_downloads(self, docname, doctree):
+        """Process downloadable file paths. """
+        for node in doctree.traverse(addnodes.download_reference):
+            targetname = node['reftarget']
+            rel_filename, filename = self.relfn2path(targetname, docname)
+            self.dependencies.setdefault(docname, set()).add(rel_filename)
+            if not os.access(filename, os.R_OK):
+                self.warn_node('download file not readable: %s' % filename,
+                               node)
+                continue
+            uniquename = self.dlfiles.add_file(docname, filename)
+            node['filename'] = uniquename
+
+    def process_images(self, docname, doctree):
+        """Process and rewrite image URIs."""
+        for node in doctree.traverse(nodes.image):
+            # Map the mimetype to the corresponding image.  The writer may
+            # choose the best image from these candidates.  The special key * is
+            # set if there is only single candidate to be used by a writer.
+            # The special key ? is set for nonlocal URIs.
+            node['candidates'] = candidates = {}
+            imguri = node['uri']
+            if imguri.find('://') != -1:
+                self.warn_node('nonlocal image URI found: %s' % imguri, node)
+                candidates['?'] = imguri
+                continue
+            rel_imgpath, full_imgpath = self.relfn2path(imguri, docname)
+            # set imgpath as default URI
+            node['uri'] = rel_imgpath
+            if rel_imgpath.endswith(os.extsep + '*'):
+                for filename in glob(full_imgpath):
+                    new_imgpath = relative_path(self.srcdir, filename)
+                    if filename.lower().endswith('.pdf'):
+                        candidates['application/pdf'] = new_imgpath
+                    elif filename.lower().endswith('.svg'):
+                        candidates['image/svg+xml'] = new_imgpath
+                    else:
+                        try:
+                            f = open(filename, 'rb')
+                            try:
+                                imgtype = imghdr.what(f)
+                            finally:
+                                f.close()
+                        except (OSError, IOError), err:
+                            self.warn_node('image file %s not readable: %s' %
+                                           (filename, err), node)
+                        if imgtype:
+                            candidates['image/' + imgtype] = new_imgpath
+            else:
+                candidates['*'] = rel_imgpath
+            # map image paths to unique image names (so that they can be put
+            # into a single directory)
+            for imgpath in candidates.itervalues():
+                self.dependencies.setdefault(docname, set()).add(imgpath)
+                if not os.access(path.join(self.srcdir, imgpath), os.R_OK):
+                    self.warn_node('image file not readable: %s' % imgpath,
+                                   node)
+                    continue
+                self.images.add_file(docname, imgpath)
+
+    def process_metadata(self, docname, doctree):
+        """Process the docinfo part of the doctree as metadata.
+
+        Keep processing minimal -- just return what docutils says.
+        """
+        self.metadata[docname] = md = {}
+        try:
+            docinfo = doctree[0]
+        except IndexError:
+            # probably an empty document
+            return
+        if docinfo.__class__ is not nodes.docinfo:
+            # nothing to see here
+            return
+        for node in docinfo:
+            # nodes are multiply inherited...
+            if isinstance(node, nodes.authors):
+                md['authors'] = [author.astext() for author in node]
+            elif isinstance(node, nodes.TextElement): # e.g. author
+                md[node.__class__.__name__] = node.astext()
+            else:
+                name, body = node
+                md[name.astext()] = body.astext()
+        del doctree[0]
+
+    def process_refonly_bullet_lists(self, docname, doctree):
+        """Change refonly bullet lists to use compact_paragraphs.
+
+        Specifically implemented for 'Indices and Tables' section, which looks
+        odd when html_compact_lists is false.
+        """
+        if self.config.html_compact_lists:
+            return
+
+        class RefOnlyListChecker(nodes.GenericNodeVisitor):
+            """Raise `nodes.NodeFound` if non-simple list item is encountered.
+
+            Here 'simple' means a list item containing only a paragraph with a
+            single reference in it.
+            """
+
+            def default_visit(self, node):
+                raise nodes.NodeFound
+
+            def visit_bullet_list(self, node):
+                pass
+
+            def visit_list_item(self, node):
+                children = []
+                for child in node.children:
+                    if not isinstance(child, nodes.Invisible):
+                        children.append(child)
+                if len(children) != 1:
+                    raise nodes.NodeFound
+                if not isinstance(children[0], nodes.paragraph):
+                    raise nodes.NodeFound
+                para = children[0]
+                if len(para) != 1:
+                    raise nodes.NodeFound
+                if not isinstance(para[0], addnodes.pending_xref):
+                    raise nodes.NodeFound
+                raise nodes.SkipChildren
+
+            def invisible_visit(self, node):
+                """Invisible nodes should be ignored."""
+                pass
+
+        def check_refonly_list(node):
+            """Check for list with only references in it."""
+            visitor = RefOnlyListChecker(doctree)
+            try:
+                node.walk(visitor)
+            except nodes.NodeFound:
+                return False
+            else:
+                return True
+
+        for node in doctree.traverse(nodes.bullet_list):
+            if check_refonly_list(node):
+                for item in node.traverse(nodes.list_item):
+                    para = item[0]
+                    ref = para[0]
+                    compact_para = addnodes.compact_paragraph()
+                    compact_para += ref
+                    item.replace(para, compact_para)
+
+    def create_title_from(self, docname, document):
+        """Add a title node to the document (just copy the first section title),
+        and store that title in the environment.
+        """
+        titlenode = nodes.title()
+        longtitlenode = titlenode
+        # explicit title set with title directive; use this only for
+        # the <title> tag in HTML output
+        if document.has_key('title'):
+            longtitlenode = nodes.title()
+            longtitlenode += nodes.Text(document['title'])
+        # look for first section title and use that as the title
+        for node in document.traverse(nodes.section):
+            visitor = SphinxContentsFilter(document)
+            node[0].walkabout(visitor)
+            titlenode += visitor.get_entry_text()
+            break
+        else:
+            # document has no title
+            titlenode += nodes.Text('<no title>')
+        self.titles[docname] = titlenode
+        self.longtitles[docname] = longtitlenode
+
+    def note_indexentries_from(self, docname, document):
+        entries = self.indexentries[docname] = []
+        for node in document.traverse(addnodes.index):
+            entries.extend(node['entries'])
+
+    def note_citations_from(self, docname, document):
+        for node in document.traverse(nodes.citation):
+            label = node[0].astext()
+            if label in self.citations:
+                self.warn_node('duplicate citation %s, ' % label +
+                               'other instance in %s' % self.doc2path(
+                                   self.citations[label][0]), node)
+            self.citations[label] = (docname, node['ids'][0])
+
+    def note_toctree(self, docname, toctreenode):
+        """Note a TOC tree directive in a document and gather information about
+        file relations from it.
+        """
+        if toctreenode['glob']:
+            self.glob_toctrees.add(docname)
+        if toctreenode.get('numbered'):
+            self.numbered_toctrees.add(docname)
+        includefiles = toctreenode['includefiles']
+        for includefile in includefiles:
+            # note that if the included file is rebuilt, this one must be
+            # too (since the TOC of the included file could have changed)
+            self.files_to_rebuild.setdefault(includefile, set()).add(docname)
+        self.toctree_includes.setdefault(docname, []).extend(includefiles)
+
+    def build_toc_from(self, docname, document):
+        """Build a TOC from the doctree and store it in the inventory."""
+        numentries = [0] # nonlocal again...
+
+        try:
+            maxdepth = int(self.metadata[docname].get('tocdepth', 0))
+        except ValueError:
+            maxdepth = 0
+
+        def traverse_in_section(node, cls):
+            """Like traverse(), but stay within the same section."""
+            result = []
+            if isinstance(node, cls):
+                result.append(node)
+            for child in node.children:
+                if isinstance(child, nodes.section):
+                    continue
+                result.extend(traverse_in_section(child, cls))
+            return result
+
+        def build_toc(node, depth=1):
+            entries = []
+            for sectionnode in node:
+                # find all toctree nodes in this section and add them
+                # to the toc (just copying the toctree node which is then
+                # resolved in self.get_and_resolve_doctree)
+                if isinstance(sectionnode, addnodes.only):
+                    onlynode = addnodes.only(expr=sectionnode['expr'])
+                    blist = build_toc(sectionnode, depth)
+                    if blist:
+                        onlynode += blist.children
+                        entries.append(onlynode)
+                if not isinstance(sectionnode, nodes.section):
+                    for toctreenode in traverse_in_section(sectionnode,
+                                                           addnodes.toctree):
+                        item = toctreenode.copy()
+                        entries.append(item)
+                        # important: do the inventory stuff
+                        self.note_toctree(docname, toctreenode)
+                    continue
+                title = sectionnode[0]
+                # copy the contents of the section title, but without references
+                # and unnecessary stuff
+                visitor = SphinxContentsFilter(document)
+                title.walkabout(visitor)
+                nodetext = visitor.get_entry_text()
+                if not numentries[0]:
+                    # for the very first toc entry, don't add an anchor
+                    # as it is the file's title anyway
+                    anchorname = ''
+                else:
+                    anchorname = '#' + sectionnode['ids'][0]
+                numentries[0] += 1
+                # make these nodes:
+                # list_item -> compact_paragraph -> reference
+                reference = nodes.reference(
+                    '', '', internal=True, refuri=docname,
+                    anchorname=anchorname, *nodetext)
+                para = addnodes.compact_paragraph('', '', reference)
+                item = nodes.list_item('', para)
+                if maxdepth == 0 or depth < maxdepth:
+                    item += build_toc(sectionnode, depth+1)
+                entries.append(item)
+            if entries:
+                return nodes.bullet_list('', *entries)
+            return []
+        toc = build_toc(document)
+        if toc:
+            self.tocs[docname] = toc
+        else:
+            self.tocs[docname] = nodes.bullet_list('')
+        self.toc_num_entries[docname] = numentries[0]
+
+    def get_toc_for(self, docname, builder):
+        """Return a TOC nodetree -- for use on the same page only!"""
+        try:
+            toc = self.tocs[docname].deepcopy()
+        except KeyError:
+            # the document does not exist anymore: return a dummy node that
+            # renders to nothing
+            return nodes.paragraph()
+        self.process_only_nodes(toc, builder, docname)
+        for node in toc.traverse(nodes.reference):
+            node['refuri'] = node['anchorname'] or '#'
+        return toc
+
+    def get_toctree_for(self, docname, builder, collapse, **kwds):
+        """Return the global TOC nodetree."""
+        doctree = self.get_doctree(self.config.master_doc)
+        toctrees = []
+        if 'includehidden' not in kwds:
+            kwds['includehidden'] = True
+        if 'maxdepth' not in kwds:
+            kwds['maxdepth'] = 0
+        kwds['collapse'] = collapse
+        for toctreenode in doctree.traverse(addnodes.toctree):
+            toctree = self.resolve_toctree(docname, builder, toctreenode,
+                                           prune=True, **kwds)
+            toctrees.append(toctree)
+        if not toctrees:
+            return None
+        result = toctrees[0]
+        for toctree in toctrees[1:]:
+            result.extend(toctree.children)
+        return result
+
+    def get_domain(self, domainname):
+        """Return the domain instance with the specified name.
+
+        Raises an ExtensionError if the domain is not registered.
+        """
+        try:
+            return self.domains[domainname]
+        except KeyError:
+            raise ExtensionError('Domain %r is not registered' % domainname)
+
+    # --------- RESOLVING REFERENCES AND TOCTREES ------------------------------
+
+    def get_doctree(self, docname):
+        """Read the doctree for a file from the pickle and return it."""
+        doctree_filename = self.doc2path(docname, self.doctreedir, '.doctree')
+        f = open(doctree_filename, 'rb')
+        try:
+            doctree = pickle.load(f)
+        finally:
+            f.close()
+        doctree.settings.env = self
+        doctree.reporter = Reporter(self.doc2path(docname), 2, 5,
+                                    stream=WarningStream(self._warnfunc))
+        return doctree
+
+
+    def get_and_resolve_doctree(self, docname, builder, doctree=None,
+                                prune_toctrees=True):
+        """Read the doctree from the pickle, resolve cross-references and
+        toctrees and return it.
+        """
+        if doctree is None:
+            doctree = self.get_doctree(docname)
+
+        # resolve all pending cross-references
+        self.resolve_references(doctree, docname, builder)
+
+        # now, resolve all toctree nodes
+        for toctreenode in doctree.traverse(addnodes.toctree):
+            result = self.resolve_toctree(docname, builder, toctreenode,
+                                          prune=prune_toctrees)
+            if result is None:
+                toctreenode.replace_self([])
+            else:
+                toctreenode.replace_self(result)
+
+        return doctree
+
+    def resolve_toctree(self, docname, builder, toctree, prune=True, maxdepth=0,
+                        titles_only=False, collapse=False, includehidden=False):
+        """Resolve a *toctree* node into individual bullet lists with titles
+        as items, returning None (if no containing titles are found) or
+        a new node.
+
+        If *prune* is True, the tree is pruned to *maxdepth*, or if that is 0,
+        to the value of the *maxdepth* option on the *toctree* node.
+        If *titles_only* is True, only toplevel document titles will be in the
+        resulting tree.
+        If *collapse* is True, all branches not containing docname will
+        be collapsed.
+        """
+        if toctree.get('hidden', False) and not includehidden:
+            return None
+
+        def _walk_depth(node, depth, maxdepth):
+            """Utility: Cut a TOC at a specified depth."""
+
+            # For reading this function, it is useful to keep in mind the node
+            # structure of a toctree (using HTML-like node names for brevity):
+            #
+            # <ul>
+            #   <li>
+            #     <p><a></p>
+            #     <p><a></p>
+            #     ...
+            #     <ul>
+            #       ...
+            #     </ul>
+            #   </li>
+            # </ul>
+
+            for subnode in node.children[:]:
+                if isinstance(subnode, (addnodes.compact_paragraph,
+                                        nodes.list_item)):
+                    # for <p> and <li>, just indicate the depth level and
+                    # recurse to children
+                    subnode['classes'].append('toctree-l%d' % (depth-1))
+                    _walk_depth(subnode, depth, maxdepth)
+
+                elif isinstance(subnode, nodes.bullet_list):
+                    # for <ul>, determine if the depth is too large or if the
+                    # entry is to be collapsed
+                    if maxdepth > 0 and depth > maxdepth:
+                        subnode.parent.replace(subnode, [])
+                    else:
+                        # to find out what to collapse, *first* walk subitems,
+                        # since that determines which children point to the
+                        # current page
+                        _walk_depth(subnode, depth+1, maxdepth)
+                        # cull sub-entries whose parents aren't 'current'
+                        if (collapse and depth > 1 and
+                            'iscurrent' not in subnode.parent):
+                            subnode.parent.remove(subnode)
+
+                elif isinstance(subnode, nodes.reference):
+                    # for <a>, identify which entries point to the current
+                    # document and therefore may not be collapsed
+                    if subnode['refuri'] == docname:
+                        if not subnode['anchorname']:
+                            # give the whole branch a 'current' class
+                            # (useful for styling it differently)
+                            branchnode = subnode
+                            while branchnode:
+                                branchnode['classes'].append('current')
+                                branchnode = branchnode.parent
+                        # mark the list_item as "on current page"
+                        if subnode.parent.parent.get('iscurrent'):
+                            # but only if it's not already done
+                            return
+                        while subnode:
+                            subnode['iscurrent'] = True
+                            subnode = subnode.parent
+
+        def _entries_from_toctree(toctreenode, parents,
+                                  separate=False, subtree=False):
+            """Return TOC entries for a toctree node."""
+            refs = [(e[0], str(e[1])) for e in toctreenode['entries']]
+            entries = []
+            for (title, ref) in refs:
+                try:
+                    refdoc = None
+                    if url_re.match(ref):
+                        reference = nodes.reference('', '', internal=False,
+                                                    refuri=ref, anchorname='',
+                                                    *[nodes.Text(title)])
+                        para = addnodes.compact_paragraph('', '', reference)
+                        item = nodes.list_item('', para)
+                        toc = nodes.bullet_list('', item)
+                    elif ref == 'self':
+                        # 'self' refers to the document from which this
+                        # toctree originates
+                        ref = toctreenode['parent']
+                        if not title:
+                            title = clean_astext(self.titles[ref])
+                        reference = nodes.reference('', '', internal=True,
+                                                    refuri=ref,
+                                                    anchorname='',
+                                                    *[nodes.Text(title)])
+                        para = addnodes.compact_paragraph('', '', reference)
+                        item = nodes.list_item('', para)
+                        # don't show subitems
+                        toc = nodes.bullet_list('', item)
+                    else:
+                        if ref in parents:
+                            self.warn(ref, 'circular toctree references '
+                                      'detected, ignoring: %s <- %s' %
+                                      (ref, ' <- '.join(parents)))
+                            continue
+                        refdoc = ref
+                        toc = self.tocs[ref].deepcopy()
+                        self.process_only_nodes(toc, builder, ref)
+                        if title and toc.children and len(toc.children) == 1:
+                            child = toc.children[0]
+                            for refnode in child.traverse(nodes.reference):
+                                if refnode['refuri'] == ref and \
+                                       not refnode['anchorname']:
+                                    refnode.children = [nodes.Text(title)]
+                    if not toc.children:
+                        # empty toc means: no titles will show up in the toctree
+                        self.warn_node(
+                            'toctree contains reference to document %r that '
+                            'doesn\'t have a title: no link will be generated'
+                            % ref, toctreenode)
+                except KeyError:
+                    # this is raised if the included file does not exist
+                    self.warn_node(
+                        'toctree contains reference to nonexisting document %r'
+                        % ref, toctreenode)
+                else:
+                    # if titles_only is given, only keep the main title and
+                    # sub-toctrees
+                    if titles_only:
+                        # delete everything but the toplevel title(s)
+                        # and toctrees
+                        for toplevel in toc:
+                            # nodes with length 1 don't have any children anyway
+                            if len(toplevel) > 1:
+                                subtrees = toplevel.traverse(addnodes.toctree)
+                                toplevel[1][:] = subtrees
+                    # resolve all sub-toctrees
+                    for toctreenode in toc.traverse(addnodes.toctree):
+                        if not (toctreenode.get('hidden', False)
+                                and not includehidden):
+                            i = toctreenode.parent.index(toctreenode) + 1
+                            for item in _entries_from_toctree(
+                                    toctreenode, [refdoc] + parents,
+                                    subtree=True):
+                                toctreenode.parent.insert(i, item)
+                                i += 1
+                            toctreenode.parent.remove(toctreenode)
+                    if separate:
+                        entries.append(toc)
+                    else:
+                        entries.extend(toc.children)
+            if not subtree and not separate:
+                ret = nodes.bullet_list()
+                ret += entries
+                return [ret]
+            return entries
+
+        maxdepth = maxdepth or toctree.get('maxdepth', -1)
+        if not titles_only and toctree.get('titlesonly', False):
+            titles_only = True
+
+        # NOTE: previously, this was separate=True, but that leads to artificial
+        # separation when two or more toctree entries form a logical unit, so
+        # separating mode is no longer used -- it's kept here for history's sake
+        tocentries = _entries_from_toctree(toctree, [], separate=False)
+        if not tocentries:
+            return None
+
+        newnode = addnodes.compact_paragraph('', '', *tocentries)
+        newnode['toctree'] = True
+
+        # prune the tree to maxdepth and replace titles, also set level classes
+        _walk_depth(newnode, 1, prune and maxdepth or 0)
+
+        # set the target paths in the toctrees (they are not known at TOC
+        # generation time)
+        for refnode in newnode.traverse(nodes.reference):
+            if not url_re.match(refnode['refuri']):
+                refnode['refuri'] = builder.get_relative_uri(
+                    docname, refnode['refuri']) + refnode['anchorname']
+        return newnode
+
+    def resolve_references(self, doctree, fromdocname, builder):
+        for node in doctree.traverse(addnodes.pending_xref):
+            contnode = node[0].deepcopy()
+            newnode = None
+
+            typ = node['reftype']
+            target = node['reftarget']
+            refdoc = node.get('refdoc', fromdocname)
+            domain = None
+
+            try:
+                if 'refdomain' in node and node['refdomain']:
+                    # let the domain try to resolve the reference
+                    try:
+                        domain = self.domains[node['refdomain']]
+                    except KeyError:
+                        raise NoUri
+                    newnode = domain.resolve_xref(self, fromdocname, builder,
+                                                  typ, target, node, contnode)
+                # really hardwired reference types
+                elif typ == 'doc':
+                    # directly reference to document by source name;
+                    # can be absolute or relative
+                    docname = docname_join(refdoc, target)
+                    if docname in self.all_docs:
+                        if node['refexplicit']:
+                            # reference with explicit title
+                            caption = node.astext()
+                        else:
+                            caption = clean_astext(self.titles[docname])
+                        innernode = nodes.emphasis(caption, caption)
+                        newnode = nodes.reference('', '', internal=True)
+                        newnode['refuri'] = builder.get_relative_uri(
+                            fromdocname, docname)
+                        newnode.append(innernode)
+                elif typ == 'citation':
+                    docname, labelid = self.citations.get(target, ('', ''))
+                    if docname:
+                        newnode = make_refnode(builder, fromdocname, docname,
+                                               labelid, contnode)
+                # no new node found? try the missing-reference event
+                if newnode is None:
+                    newnode = builder.app.emit_firstresult(
+                        'missing-reference', self, node, contnode)
+                    # still not found? warn if in nit-picky mode
+                    if newnode is None:
+                        self._warn_missing_reference(
+                            fromdocname, typ, target, node, domain)
+            except NoUri:
+                newnode = contnode
+            node.replace_self(newnode or contnode)
+
+        # remove only-nodes that do not belong to our builder
+        self.process_only_nodes(doctree, builder, fromdocname)
+
+        # allow custom references to be resolved
+        builder.app.emit('doctree-resolved', doctree, fromdocname)
+
+    def _warn_missing_reference(self, fromdoc, typ, target, node, domain):
+        warn = node.get('refwarn')
+        if self.config.nitpicky:
+            warn = True
+            if self._nitpick_ignore:
+                dtype = domain and '%s:%s' % (domain.name, typ) or typ
+                if (dtype, target) in self._nitpick_ignore:
+                    warn = False
+        if not warn:
+            return
+        if domain and typ in domain.dangling_warnings:
+            msg = domain.dangling_warnings[typ]
+        elif typ == 'doc':
+            msg = 'unknown document: %(target)s'
+        elif typ == 'citation':
+            msg = 'citation not found: %(target)s'
+        elif node.get('refdomain', 'std') != 'std':
+            msg = '%s:%s reference target not found: %%(target)s' % \
+                  (node['refdomain'], typ)
+        else:
+            msg = '%s reference target not found: %%(target)s' % typ
+        self.warn_node(msg % {'target': target}, node)
+
+    def process_only_nodes(self, doctree, builder, fromdocname=None):
+        # A comment on the comment() nodes being inserted: replacing by [] would
+        # result in a "Losing ids" exception if there is a target node before
+        # the only node, so we make sure docutils can transfer the id to
+        # something, even if it's just a comment and will lose the id anyway...
+        for node in doctree.traverse(addnodes.only):
+            try:
+                ret = builder.tags.eval_condition(node['expr'])
+            except Exception, err:
+                self.warn_node('exception while evaluating only '
+                               'directive expression: %s' % err, node)
+                node.replace_self(node.children or nodes.comment())
+            else:
+                if ret:
+                    node.replace_self(node.children or nodes.comment())
+                else:
+                    node.replace_self(nodes.comment())
+
+    def assign_section_numbers(self):
+        """Assign a section number to each heading under a numbered toctree."""
+        # a list of all docnames whose section numbers changed
+        rewrite_needed = []
+
+        old_secnumbers = self.toc_secnumbers
+        self.toc_secnumbers = {}
+
+        def _walk_toc(node, secnums, depth, titlenode=None):
+            # titlenode is the title of the document, it will get assigned a
+            # secnumber too, so that it shows up in next/prev/parent rellinks
+            for subnode in node.children:
+                if isinstance(subnode, nodes.bullet_list):
+                    numstack.append(0)
+                    _walk_toc(subnode, secnums, depth-1, titlenode)
+                    numstack.pop()
+                    titlenode = None
+                elif isinstance(subnode, nodes.list_item):
+                    _walk_toc(subnode, secnums, depth, titlenode)
+                    titlenode = None
+                elif isinstance(subnode, addnodes.only):
+                    # at this stage we don't know yet which sections are going
+                    # to be included; just include all of them, even if it leads
+                    # to gaps in the numbering
+                    _walk_toc(subnode, secnums, depth, titlenode)
+                    titlenode = None
+                elif isinstance(subnode, addnodes.compact_paragraph):
+                    numstack[-1] += 1
+                    if depth > 0:
+                        number = tuple(numstack)
+                    else:
+                        number = None
+                    secnums[subnode[0]['anchorname']] = \
+                        subnode[0]['secnumber'] = number
+                    if titlenode:
+                        titlenode['secnumber'] = number
+                        titlenode = None
+                elif isinstance(subnode, addnodes.toctree):
+                    _walk_toctree(subnode, depth)
+
+        def _walk_toctree(toctreenode, depth):
+            if depth == 0:
+                return
+            for (title, ref) in toctreenode['entries']:
+                if url_re.match(ref) or ref == 'self':
+                    # don't mess with those
+                    continue
+                if ref in self.tocs:
+                    secnums = self.toc_secnumbers[ref] = {}
+                    _walk_toc(self.tocs[ref], secnums, depth,
+                              self.titles.get(ref))
+                    if secnums != old_secnumbers.get(ref):
+                        rewrite_needed.append(ref)
+
+        for docname in self.numbered_toctrees:
+            doctree = self.get_doctree(docname)
+            for toctreenode in doctree.traverse(addnodes.toctree):
+                depth = toctreenode.get('numbered', 0)
+                if depth:
+                    # every numbered toctree gets new numbering
+                    numstack = [0]
+                    _walk_toctree(toctreenode, depth)
+
+        return rewrite_needed
+
+    def create_index(self, builder, group_entries=True,
+                     _fixre=re.compile(r'(.*) ([(][^()]*[)])')):
+        """Create the real index from the collected index entries."""
+        new = {}
+
+        def add_entry(word, subword, link=True, dic=new):
+            entry = dic.get(word)
+            if not entry:
+                dic[word] = entry = [[], {}]
+            if subword:
+                add_entry(subword, '', link=link, dic=entry[1])
+            elif link:
+                try:
+                    uri = builder.get_relative_uri('genindex', fn) + '#' + tid
+                except NoUri:
+                    pass
+                else:
+                    entry[0].append((main, uri))
+
+        for fn, entries in self.indexentries.iteritems():
+            # new entry types must be listed in directives/other.py!
+            for type, value, tid, main in entries:
+                try:
+                    if type == 'single':
+                        try:
+                            entry, subentry = split_into(2, 'single', value)
+                        except ValueError:
+                            entry, = split_into(1, 'single', value)
+                            subentry = ''
+                        add_entry(entry, subentry)
+                    elif type == 'pair':
+                        first, second = split_into(2, 'pair', value)
+                        add_entry(first, second)
+                        add_entry(second, first)
+                    elif type == 'triple':
+                        first, second, third = split_into(3, 'triple', value)
+                        add_entry(first, second+' '+third)
+                        add_entry(second, third+', '+first)
+                        add_entry(third, first+' '+second)
+                    elif type == 'see':
+                        first, second = split_into(2, 'see', value)
+                        add_entry(first, _('see %s') % second, link=False)
+                    elif type == 'seealso':
+                        first, second = split_into(2, 'see', value)
+                        add_entry(first, _('see also %s') % second, link=False)
+                    else:
+                        self.warn(fn, 'unknown index entry type %r' % type)
+                except ValueError, err:
+                    self.warn(fn, str(err))
+
+        # sort the index entries; put all symbols at the front, even those
+        # following the letters in ASCII, this is where the chr(127) comes from
+        def keyfunc(entry, lcletters=string.ascii_lowercase + '_'):
+            lckey = unicodedata.normalize('NFD', entry[0].lower())
+            if lckey[0:1] in lcletters:
+                return chr(127) + lckey
+            return lckey
+        newlist = new.items()
+        newlist.sort(key=keyfunc)
+
+        if group_entries:
+            # fixup entries: transform
+            #   func() (in module foo)
+            #   func() (in module bar)
+            # into
+            #   func()
+            #     (in module foo)
+            #     (in module bar)
+            oldkey = ''
+            oldsubitems = None
+            i = 0
+            while i < len(newlist):
+                key, (targets, subitems) = newlist[i]
+                # cannot move if it has subitems; structure gets too complex
+                if not subitems:
+                    m = _fixre.match(key)
+                    if m:
+                        if oldkey == m.group(1):
+                            # prefixes match: add entry as subitem of the
+                            # previous entry
+                            oldsubitems.setdefault(m.group(2), [[], {}])[0].\
+                                        extend(targets)
+                            del newlist[i]
+                            continue
+                        oldkey = m.group(1)
+                    else:
+                        oldkey = key
+                oldsubitems = subitems
+                i += 1
+
+        # group the entries by letter
+        def keyfunc2(item, letters=string.ascii_uppercase + '_'):
+            # hack: mutating the subitems dicts to a list in the keyfunc
+            k, v = item
+            v[1] = sorted((si, se) for (si, (se, void)) in v[1].iteritems())
+            # now calculate the key
+            letter = unicodedata.normalize('NFD', k[0])[0].upper()
+            if letter in letters:
+                return letter
+            else:
+                # get all other symbols under one heading
+                return 'Symbols'
+        return [(key, list(group))
+                for (key, group) in groupby(newlist, keyfunc2)]
+
+    def collect_relations(self):
+        relations = {}
+        getinc = self.toctree_includes.get
+        def collect(parents, parents_set, docname, previous, next):
+            # circular relationship?
+            if docname in parents_set:
+                # we will warn about this in resolve_toctree()
+                return
+            includes = getinc(docname)
+            # previous
+            if not previous:
+                # if no previous sibling, go to parent
+                previous = parents[0][0]
+            else:
+                # else, go to previous sibling, or if it has children, to
+                # the last of its children, or if that has children, to the
+                # last of those, and so forth
+                while 1:
+                    previncs = getinc(previous)
+                    if previncs:
+                        previous = previncs[-1]
+                    else:
+                        break
+            # next
+            if includes:
+                # if it has children, go to first of them
+                next = includes[0]
+            elif next:
+                # else, if next sibling, go to it
+                pass
+            else:
+                # else, go to the next sibling of the parent, if present,
+                # else the grandparent's sibling, if present, and so forth
+                for parname, parindex in parents:
+                    parincs = getinc(parname)
+                    if parincs and parindex + 1 < len(parincs):
+                        next = parincs[parindex+1]
+                        break
+                # else it will stay None
+            # same for children
+            if includes:
+                for subindex, args in enumerate(izip(includes,
+                                                     [None] + includes,
+                                                     includes[1:] + [None])):
+                    collect([(docname, subindex)] + parents,
+                            parents_set.union([docname]), *args)
+            relations[docname] = [parents[0][0], previous, next]
+        collect([(None, 0)], set(), self.config.master_doc, None, None)
+        return relations
+
+    def check_consistency(self):
+        """Do consistency checks."""
+        for docname in sorted(self.all_docs):
+            if docname not in self.files_to_rebuild:
+                if docname == self.config.master_doc:
+                    # the master file is not included anywhere ;)
+                    continue
+                if 'orphan' in self.metadata[docname]:
+                    continue
+                self.warn(docname, 'document isn\'t included in any toctree')
+

=== added directory '.pc/sort_stopwords.diff'
=== added directory '.pc/sort_stopwords.diff/sphinx'
=== added directory '.pc/sort_stopwords.diff/sphinx/search'
=== added file '.pc/sort_stopwords.diff/sphinx/search/__init__.py'
--- .pc/sort_stopwords.diff/sphinx/search/__init__.py	1970-01-01 00:00:00 +0000
+++ .pc/sort_stopwords.diff/sphinx/search/__init__.py	2012-11-28 07:12:20 +0000
@@ -0,0 +1,287 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.search
+    ~~~~~~~~~~~~~
+
+    Create a full-text search index for offline search.
+
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+import re
+import cPickle as pickle
+
+from docutils.nodes import comment, Text, NodeVisitor, SkipNode
+
+from sphinx.util import jsdump, rpartition
+
+
+class SearchLanguage(object):
+    """
+    This class is the base class for search natural language preprocessors.  If
+    you want to add support for a new language, you should override the methods
+    of this class.
+
+    You should override `lang` class property too (e.g. 'en', 'fr' and so on).
+
+    .. attribute:: stopwords
+
+       This is a set of stop words of the target language.  Default `stopwords`
+       is empty.  This word is used for building index and embedded in JS.
+
+    .. attribute:: js_stemmer_code
+
+       Return stemmer class of JavaScript version.  This class' name should be
+       ``Stemmer`` and this class must have ``stemWord`` method.  This string is
+       embedded as-is in searchtools.js.
+
+       This class is used to preprocess search word which Sphinx HTML readers
+       type, before searching index. Default implementation does nothing.
+    """
+    lang = None
+    stopwords = set()
+    js_stemmer_code = """
+/**
+ * Dummy stemmer for languages without stemming rules.
+ */
+var Stemmer = function() {
+  this.stemWord = function(w) {
+    return w;
+  }
+}
+"""
+
+    _word_re = re.compile(r'\w+(?u)')
+
+    def __init__(self, options):
+        self.options = options
+        self.init(options)
+
+    def init(self, options):
+        """
+        Initialize the class with the options the user has given.
+        """
+
+    def split(self, input):
+        """
+        This method splits a sentence into words.  Default splitter splits input
+        at white spaces, which should be enough for most languages except CJK
+        languages.
+        """
+        return self._word_re.findall(input)
+
+    def stem(self, word):
+        """
+        This method implements stemming algorithm of the Python version.
+
+        Default implementation does nothing.  You should implement this if the
+        language has any stemming rules.
+
+        This class is used to preprocess search words before registering them in
+        the search index.  The stemming of the Python version and the JS version
+        (given in the js_stemmer_code attribute) must be compatible.
+        """
+        return word
+
+    def word_filter(self, word):
+        """
+        Return true if the target word should be registered in the search index.
+        This method is called after stemming.
+        """
+        return not (((len(word) < 3) and (12353 < ord(word[0]) < 12436)) or
+            (ord(word[0]) < 256 and (len(word) < 3 or word in self.stopwords or
+                                     word.isdigit())))
+
+from sphinx.search import en, ja
+
+languages = {
+    'en': en.SearchEnglish,
+    'ja': ja.SearchJapanese,
+}
+
+
+class _JavaScriptIndex(object):
+    """
+    The search index as javascript file that calls a function
+    on the documentation search object to register the index.
+    """
+
+    PREFIX = 'Search.setIndex('
+    SUFFIX = ')'
+
+    def dumps(self, data):
+        return self.PREFIX + jsdump.dumps(data) + self.SUFFIX
+
+    def loads(self, s):
+        data = s[len(self.PREFIX):-len(self.SUFFIX)]
+        if not data or not s.startswith(self.PREFIX) or not \
+           s.endswith(self.SUFFIX):
+            raise ValueError('invalid data')
+        return jsdump.loads(data)
+
+    def dump(self, data, f):
+        f.write(self.dumps(data))
+
+    def load(self, f):
+        return self.loads(f.read())
+
+
+js_index = _JavaScriptIndex()
+
+
+class WordCollector(NodeVisitor):
+    """
+    A special visitor that collects words for the `IndexBuilder`.
+    """
+
+    def __init__(self, document, lang):
+        NodeVisitor.__init__(self, document)
+        self.found_words = []
+        self.lang = lang
+
+    def dispatch_visit(self, node):
+        if node.__class__ is comment:
+            raise SkipNode
+        if node.__class__ is Text:
+            self.found_words.extend(self.lang.split(node.astext()))
+
+
+class IndexBuilder(object):
+    """
+    Helper class that creates a searchindex based on the doctrees
+    passed to the `feed` method.
+    """
+    formats = {
+        'jsdump':   jsdump,
+        'pickle':   pickle
+    }
+
+    def __init__(self, env, lang, options):
+        self.env = env
+        # filename -> title
+        self._titles = {}
+        # stemmed word -> set(filenames)
+        self._mapping = {}
+        # objtype -> index
+        self._objtypes = {}
+        # objtype index -> (domain, type, objname (localized))
+        self._objnames = {}
+        # add language-specific SearchLanguage instance
+        self.lang = languages[lang](options)
+
+    def load(self, stream, format):
+        """Reconstruct from frozen data."""
+        if isinstance(format, basestring):
+            format = self.formats[format]
+        frozen = format.load(stream)
+        # if an old index is present, we treat it as not existing.
+        if not isinstance(frozen, dict):
+            raise ValueError('old format')
+        index2fn = frozen['filenames']
+        self._titles = dict(zip(index2fn, frozen['titles']))
+        self._mapping = {}
+        for k, v in frozen['terms'].iteritems():
+            if isinstance(v, int):
+                self._mapping[k] = set([index2fn[v]])
+            else:
+                self._mapping[k] = set(index2fn[i] for i in v)
+        # no need to load keywords/objtypes
+
+    def dump(self, stream, format):
+        """Dump the frozen index to a stream."""
+        if isinstance(format, basestring):
+            format = self.formats[format]
+        format.dump(self.freeze(), stream)
+
+    def get_objects(self, fn2index):
+        rv = {}
+        otypes = self._objtypes
+        onames = self._objnames
+        for domainname, domain in self.env.domains.iteritems():
+            for fullname, dispname, type, docname, anchor, prio in \
+                    domain.get_objects():
+                # XXX use dispname?
+                if docname not in fn2index:
+                    continue
+                if prio < 0:
+                    continue
+                prefix, name = rpartition(fullname, '.')
+                pdict = rv.setdefault(prefix, {})
+                try:
+                    typeindex = otypes[domainname, type]
+                except KeyError:
+                    typeindex = len(otypes)
+                    otypes[domainname, type] = typeindex
+                    otype = domain.object_types.get(type)
+                    if otype:
+                        # use unicode() to fire translation proxies
+                        onames[typeindex] = (domainname, type,
+                            unicode(domain.get_type_name(otype)))
+                    else:
+                        onames[typeindex] = (domainname, type, type)
+                if anchor == fullname:
+                    shortanchor = ''
+                elif anchor == type + '-' + fullname:
+                    shortanchor = '-'
+                else:
+                    shortanchor = anchor
+                pdict[name] = (fn2index[docname], typeindex, prio, shortanchor)
+        return rv
+
+    def get_terms(self, fn2index):
+        rv = {}
+        for k, v in self._mapping.iteritems():
+            if len(v) == 1:
+                fn, = v
+                if fn in fn2index:
+                    rv[k] = fn2index[fn]
+            else:
+                rv[k] = [fn2index[fn] for fn in v if fn in fn2index]
+        return rv
+
+    def freeze(self):
+        """Create a usable data structure for serializing."""
+        filenames = self._titles.keys()
+        titles = self._titles.values()
+        fn2index = dict((f, i) for (i, f) in enumerate(filenames))
+        terms = self.get_terms(fn2index)
+        objects = self.get_objects(fn2index)  # populates _objtypes
+        objtypes = dict((v, k[0] + ':' + k[1])
+                        for (k, v) in self._objtypes.iteritems())
+        objnames = self._objnames
+        return dict(filenames=filenames, titles=titles, terms=terms,
+                    objects=objects, objtypes=objtypes, objnames=objnames)
+
+    def prune(self, filenames):
+        """Remove data for all filenames not in the list."""
+        new_titles = {}
+        for filename in filenames:
+            if filename in self._titles:
+                new_titles[filename] = self._titles[filename]
+        self._titles = new_titles
+        for wordnames in self._mapping.itervalues():
+            wordnames.intersection_update(filenames)
+
+    def feed(self, filename, title, doctree):
+        """Feed a doctree to the index."""
+        self._titles[filename] = title
+
+        visitor = WordCollector(doctree, self.lang)
+        doctree.walk(visitor)
+
+        def add_term(word, stem=self.lang.stem):
+            word = stem(word)
+            if self.lang.word_filter(word):
+                self._mapping.setdefault(word, set()).add(filename)
+
+        for word in self.lang.split(title):
+            add_term(word)
+
+        for word in visitor.found_words:
+            add_term(word)
+
+    def context_for_searchtool(self):
+        return dict(
+            search_language_stemming_code = self.lang.js_stemmer_code,
+            search_language_stop_words = jsdump.dumps(self.lang.stopwords),
+        )

=== removed file '.pc/support_python_3.3.diff/sphinx/environment.py'
--- .pc/support_python_3.3.diff/sphinx/environment.py	2012-11-01 21:39:16 +0000
+++ .pc/support_python_3.3.diff/sphinx/environment.py	1970-01-01 00:00:00 +0000
@@ -1,1762 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-    sphinx.environment
-    ~~~~~~~~~~~~~~~~~~
-
-    Global creation environment.
-
-    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-"""
-
-import re
-import os
-import sys
-import time
-import types
-import codecs
-import imghdr
-import string
-import unicodedata
-import cPickle as pickle
-from os import path
-from glob import glob
-from itertools import izip, groupby
-
-from docutils import nodes
-from docutils.io import FileInput, NullOutput
-from docutils.core import Publisher
-from docutils.utils import Reporter, relative_path, new_document, \
-     get_source_line
-from docutils.readers import standalone
-from docutils.parsers.rst import roles, directives, Parser as RSTParser
-from docutils.parsers.rst.languages import en as english
-from docutils.parsers.rst.directives.html import MetaBody
-from docutils.writers import UnfilteredWriter
-from docutils.transforms import Transform
-from docutils.transforms.parts import ContentsFilter
-
-from sphinx import addnodes
-from sphinx.util import url_re, get_matching_docs, docname_join, split_into, \
-     FilenameUniqDict
-from sphinx.util.nodes import clean_astext, make_refnode, extract_messages, \
-     WarningStream
-from sphinx.util.osutil import movefile, SEP, ustrftime, find_catalog
-from sphinx.util.matching import compile_matchers
-from sphinx.util.pycompat import all, class_types
-from sphinx.util.websupport import is_commentable
-from sphinx.errors import SphinxError, ExtensionError
-from sphinx.locale import _, init as init_locale
-from sphinx.versioning import add_uids, merge_doctrees
-
-fs_encoding = sys.getfilesystemencoding() or sys.getdefaultencoding()
-
-orig_role_function = roles.role
-orig_directive_function = directives.directive
-
-class ElementLookupError(Exception): pass
-
-
-default_settings = {
-    'embed_stylesheet': False,
-    'cloak_email_addresses': True,
-    'pep_base_url': 'http://www.python.org/dev/peps/',
-    'rfc_base_url': 'http://tools.ietf.org/html/',
-    'input_encoding': 'utf-8-sig',
-    'doctitle_xform': False,
-    'sectsubtitle_xform': False,
-    'halt_level': 5,
-}
-
-# This is increased every time an environment attribute is added
-# or changed to properly invalidate pickle files.
-ENV_VERSION = 41
-
-
-default_substitutions = set([
-    'version',
-    'release',
-    'today',
-])
-
-dummy_reporter = Reporter('', 4, 4)
-
-versioning_conditions = {
-    'none': False,
-    'text': nodes.TextElement,
-    'commentable': is_commentable,
-}
-
-
-class NoUri(Exception):
-    """Raised by get_relative_uri if there is no URI available."""
-    pass
-
-
-class DefaultSubstitutions(Transform):
-    """
-    Replace some substitutions if they aren't defined in the document.
-    """
-    # run before the default Substitutions
-    default_priority = 210
-
-    def apply(self):
-        config = self.document.settings.env.config
-        # only handle those not otherwise defined in the document
-        to_handle = default_substitutions - set(self.document.substitution_defs)
-        for ref in self.document.traverse(nodes.substitution_reference):
-            refname = ref['refname']
-            if refname in to_handle:
-                text = config[refname]
-                if refname == 'today' and not text:
-                    # special handling: can also specify a strftime format
-                    text = ustrftime(config.today_fmt or _('%B %d, %Y'))
-                ref.replace_self(nodes.Text(text, text))
-
-
-class MoveModuleTargets(Transform):
-    """
-    Move module targets that are the first thing in a section to the section
-    title.
-
-    XXX Python specific
-    """
-    default_priority = 210
-
-    def apply(self):
-        for node in self.document.traverse(nodes.target):
-            if not node['ids']:
-                continue
-            if (node.has_key('ismod') and
-                node.parent.__class__ is nodes.section and
-                # index 0 is the section title node
-                node.parent.index(node) == 1):
-                node.parent['ids'][0:0] = node['ids']
-                node.parent.remove(node)
-
-
-class HandleCodeBlocks(Transform):
-    """
-    Several code block related transformations.
-    """
-    default_priority = 210
-
-    def apply(self):
-        # move doctest blocks out of blockquotes
-        for node in self.document.traverse(nodes.block_quote):
-            if all(isinstance(child, nodes.doctest_block) for child
-                     in node.children):
-                node.replace_self(node.children)
-        # combine successive doctest blocks
-        #for node in self.document.traverse(nodes.doctest_block):
-        #    if node not in node.parent.children:
-        #        continue
-        #    parindex = node.parent.index(node)
-        #    while len(node.parent) > parindex+1 and \
-        #            isinstance(node.parent[parindex+1], nodes.doctest_block):
-        #        node[0] = nodes.Text(node[0] + '\n\n' +
-        #                             node.parent[parindex+1][0])
-        #        del node.parent[parindex+1]
-
-
-class SortIds(Transform):
-    """
-    Sort secion IDs so that the "id[0-9]+" one comes last.
-    """
-    default_priority = 261
-
-    def apply(self):
-        for node in self.document.traverse(nodes.section):
-            if len(node['ids']) > 1 and node['ids'][0].startswith('id'):
-                node['ids'] = node['ids'][1:] + [node['ids'][0]]
-
-
-class CitationReferences(Transform):
-    """
-    Replace citation references by pending_xref nodes before the default
-    docutils transform tries to resolve them.
-    """
-    default_priority = 619
-
-    def apply(self):
-        for citnode in self.document.traverse(nodes.citation_reference):
-            cittext = citnode.astext()
-            refnode = addnodes.pending_xref(cittext, reftype='citation',
-                                            reftarget=cittext, refwarn=True)
-            refnode.line = citnode.line or citnode.parent.line
-            refnode += nodes.Text('[' + cittext + ']')
-            citnode.parent.replace(citnode, refnode)
-
-
-class Locale(Transform):
-    """
-    Replace translatable nodes with their translated doctree.
-    """
-    default_priority = 0
-    def apply(self):
-        env = self.document.settings.env
-        settings, source = self.document.settings, self.document['source']
-        # XXX check if this is reliable
-        assert source.startswith(env.srcdir)
-        docname = path.splitext(relative_path(env.srcdir, source))[0]
-        textdomain = find_catalog(docname,
-                                  self.document.settings.gettext_compact)
-
-        # fetch translations
-        dirs = [path.join(env.srcdir, directory)
-                for directory in env.config.locale_dirs]
-        catalog, has_catalog = init_locale(dirs, env.config.language,
-                                           textdomain)
-        if not has_catalog:
-            return
-
-        parser = RSTParser()
-
-        for node, msg in extract_messages(self.document):
-            patch = new_document(source, settings)
-            msgstr = catalog.gettext(msg)
-            # XXX add marker to untranslated parts
-            if not msgstr or msgstr == msg: # as-of-yet untranslated
-                continue
-            parser.parse(msgstr, patch)
-            patch = patch[0]
-            # XXX doctest and other block markup
-            if not isinstance(patch, nodes.paragraph):
-                continue # skip for now
-            for child in patch.children: # update leaves
-                child.parent = node
-            node.children = patch.children
-
-
-class SphinxStandaloneReader(standalone.Reader):
-    """
-    Add our own transforms.
-    """
-    transforms = [Locale, CitationReferences, DefaultSubstitutions,
-                  MoveModuleTargets, HandleCodeBlocks, SortIds]
-
-    def get_transforms(self):
-        return standalone.Reader.get_transforms(self) + self.transforms
-
-
-class SphinxDummyWriter(UnfilteredWriter):
-    supported = ('html',)  # needed to keep "meta" nodes
-
-    def translate(self):
-        pass
-
-
-class SphinxContentsFilter(ContentsFilter):
-    """
-    Used with BuildEnvironment.add_toc_from() to discard cross-file links
-    within table-of-contents link nodes.
-    """
-    def visit_pending_xref(self, node):
-        text = node.astext()
-        self.parent.append(nodes.literal(text, text))
-        raise nodes.SkipNode
-
-    def visit_image(self, node):
-        raise nodes.SkipNode
-
-
-class BuildEnvironment:
-    """
-    The environment in which the ReST files are translated.
-    Stores an inventory of cross-file targets and provides doctree
-    transformations to resolve links to them.
-    """
-
-    # --------- ENVIRONMENT PERSISTENCE ----------------------------------------
-
-    @staticmethod
-    def frompickle(config, filename):
-        picklefile = open(filename, 'rb')
-        try:
-            env = pickle.load(picklefile)
-        finally:
-            picklefile.close()
-        if env.version != ENV_VERSION:
-            raise IOError('env version not current')
-        env.config.values = config.values
-        return env
-
-    def topickle(self, filename):
-        # remove unpicklable attributes
-        warnfunc = self._warnfunc
-        self.set_warnfunc(None)
-        values = self.config.values
-        del self.config.values
-        domains = self.domains
-        del self.domains
-        # first write to a temporary file, so that if dumping fails,
-        # the existing environment won't be overwritten
-        picklefile = open(filename + '.tmp', 'wb')
-        # remove potentially pickling-problematic values from config
-        for key, val in vars(self.config).items():
-            if key.startswith('_') or \
-                   isinstance(val, types.ModuleType) or \
-                   isinstance(val, types.FunctionType) or \
-                   isinstance(val, class_types):
-                del self.config[key]
-        try:
-            pickle.dump(self, picklefile, pickle.HIGHEST_PROTOCOL)
-        finally:
-            picklefile.close()
-        movefile(filename + '.tmp', filename)
-        # reset attributes
-        self.domains = domains
-        self.config.values = values
-        self.set_warnfunc(warnfunc)
-
-    # --------- ENVIRONMENT INITIALIZATION -------------------------------------
-
-    def __init__(self, srcdir, doctreedir, config):
-        self.doctreedir = doctreedir
-        self.srcdir = srcdir
-        self.config = config
-
-        # the method of doctree versioning; see set_versioning_method
-        self.versioning_condition = None
-
-        # the application object; only set while update() runs
-        self.app = None
-
-        # all the registered domains, set by the application
-        self.domains = {}
-
-        # the docutils settings for building
-        self.settings = default_settings.copy()
-        self.settings['env'] = self
-
-        # the function to write warning messages with
-        self._warnfunc = None
-
-        # this is to invalidate old pickles
-        self.version = ENV_VERSION
-
-        # make this a set for faster testing
-        self._nitpick_ignore = set(self.config.nitpick_ignore)
-
-        # All "docnames" here are /-separated and relative and exclude
-        # the source suffix.
-
-        self.found_docs = set()     # contains all existing docnames
-        self.all_docs = {}          # docname -> mtime at the time of build
-                                    # contains all built docnames
-        self.dependencies = {}      # docname -> set of dependent file
-                                    # names, relative to documentation root
-        self.reread_always = set()  # docnames to re-read unconditionally on
-                                    # next build
-
-        # File metadata
-        self.metadata = {}          # docname -> dict of metadata items
-
-        # TOC inventory
-        self.titles = {}            # docname -> title node
-        self.longtitles = {}        # docname -> title node; only different if
-                                    # set differently with title directive
-        self.tocs = {}              # docname -> table of contents nodetree
-        self.toc_num_entries = {}   # docname -> number of real entries
-        # used to determine when to show the TOC
-        # in a sidebar (don't show if it's only one item)
-        self.toc_secnumbers = {}    # docname -> dict of sectionid -> number
-
-        self.toctree_includes = {}  # docname -> list of toctree includefiles
-        self.files_to_rebuild = {}  # docname -> set of files
-                                    # (containing its TOCs) to rebuild too
-        self.glob_toctrees = set()  # docnames that have :glob: toctrees
-        self.numbered_toctrees = set() # docnames that have :numbered: toctrees
-
-        # domain-specific inventories, here to be pickled
-        self.domaindata = {}        # domainname -> domain-specific dict
-
-        # Other inventories
-        self.citations = {}         # citation name -> docname, labelid
-        self.indexentries = {}      # docname -> list of
-                                    # (type, string, target, aliasname)
-        self.versionchanges = {}    # version -> list of (type, docname,
-                                    # lineno, module, descname, content)
-
-        # these map absolute path -> (docnames, unique filename)
-        self.images = FilenameUniqDict()
-        self.dlfiles = FilenameUniqDict()
-
-        # temporary data storage while reading a document
-        self.temp_data = {}
-
-    def set_warnfunc(self, func):
-        self._warnfunc = func
-        self.settings['warning_stream'] = WarningStream(func)
-
-    def set_versioning_method(self, method):
-        """This sets the doctree versioning method for this environment.
-
-        Versioning methods are a builder property; only builders with the same
-        versioning method can share the same doctree directory.  Therefore, we
-        raise an exception if the user tries to use an environment with an
-        incompatible versioning method.
-        """
-        if method not in versioning_conditions:
-            raise ValueError('invalid versioning method: %r' % method)
-        condition = versioning_conditions[method]
-        if self.versioning_condition not in (None, condition):
-            raise SphinxError('This environment is incompatible with the '
-                              'selected builder, please choose another '
-                              'doctree directory.')
-        self.versioning_condition = condition
-
-    def warn(self, docname, msg, lineno=None):
-        # strange argument order is due to backwards compatibility
-        self._warnfunc(msg, (docname, lineno))
-
-    def warn_node(self, msg, node):
-        self._warnfunc(msg, '%s:%s' % get_source_line(node))
-
-    def clear_doc(self, docname):
-        """Remove all traces of a source file in the inventory."""
-        if docname in self.all_docs:
-            self.all_docs.pop(docname, None)
-            self.reread_always.discard(docname)
-            self.metadata.pop(docname, None)
-            self.dependencies.pop(docname, None)
-            self.titles.pop(docname, None)
-            self.longtitles.pop(docname, None)
-            self.tocs.pop(docname, None)
-            self.toc_secnumbers.pop(docname, None)
-            self.toc_num_entries.pop(docname, None)
-            self.toctree_includes.pop(docname, None)
-            self.indexentries.pop(docname, None)
-            self.glob_toctrees.discard(docname)
-            self.numbered_toctrees.discard(docname)
-            self.images.purge_doc(docname)
-            self.dlfiles.purge_doc(docname)
-
-            for subfn, fnset in self.files_to_rebuild.items():
-                fnset.discard(docname)
-                if not fnset:
-                    del self.files_to_rebuild[subfn]
-            for key, (fn, _) in self.citations.items():
-                if fn == docname:
-                    del self.citations[key]
-            for version, changes in self.versionchanges.items():
-                new = [change for change in changes if change[1] != docname]
-                changes[:] = new
-
-        for domain in self.domains.values():
-            domain.clear_doc(docname)
-
-    def doc2path(self, docname, base=True, suffix=None):
-        """Return the filename for the document name.
-
-        If *base* is True, return absolute path under self.srcdir.
-        If *base* is None, return relative path to self.srcdir.
-        If *base* is a path string, return absolute path under that.
-        If *suffix* is not None, add it instead of config.source_suffix.
-        """
-        docname = docname.replace(SEP, path.sep)
-        suffix = suffix or self.config.source_suffix
-        if base is True:
-            return path.join(self.srcdir, docname) + suffix
-        elif base is None:
-            return docname + suffix
-        else:
-            return path.join(base, docname) + suffix
-
-    def relfn2path(self, filename, docname=None):
-        """Return paths to a file referenced from a document, relative to
-        documentation root and absolute.
-
-        Absolute filenames are relative to the source dir, while relative
-        filenames are relative to the dir of the containing document.
-        """
-        if filename.startswith('/') or filename.startswith(os.sep):
-            rel_fn = filename[1:]
-        else:
-            docdir = path.dirname(self.doc2path(docname or self.docname,
-                                                base=None))
-            rel_fn = path.join(docdir, filename)
-        try:
-            return rel_fn, path.join(self.srcdir, rel_fn)
-        except UnicodeDecodeError:
-            # the source directory is a bytestring with non-ASCII characters;
-            # let's try to encode the rel_fn in the file system encoding
-            enc_rel_fn = rel_fn.encode(sys.getfilesystemencoding())
-            return rel_fn, path.join(self.srcdir, enc_rel_fn)
-
-    def find_files(self, config):
-        """Find all source files in the source dir and put them in
-        self.found_docs.
-        """
-        matchers = compile_matchers(
-            config.exclude_patterns[:] +
-            config.exclude_trees +
-            [d + config.source_suffix for d in config.unused_docs] +
-            ['**/' + d for d in config.exclude_dirnames] +
-            ['**/_sources', '.#*']
-        )
-        self.found_docs = set(get_matching_docs(
-            self.srcdir, config.source_suffix, exclude_matchers=matchers))
-
-    def get_outdated_files(self, config_changed):
-        """Return (added, changed, removed) sets."""
-        # clear all files no longer present
-        removed = set(self.all_docs) - self.found_docs
-
-        added = set()
-        changed = set()
-
-        if config_changed:
-            # config values affect e.g. substitutions
-            added = self.found_docs
-        else:
-            for docname in self.found_docs:
-                if docname not in self.all_docs:
-                    added.add(docname)
-                    continue
-                # if the doctree file is not there, rebuild
-                if not path.isfile(self.doc2path(docname, self.doctreedir,
-                                                 '.doctree')):
-                    changed.add(docname)
-                    continue
-                # check the "reread always" list
-                if docname in self.reread_always:
-                    changed.add(docname)
-                    continue
-                # check the mtime of the document
-                mtime = self.all_docs[docname]
-                newmtime = path.getmtime(self.doc2path(docname))
-                if newmtime > mtime:
-                    changed.add(docname)
-                    continue
-                # finally, check the mtime of dependencies
-                for dep in self.dependencies.get(docname, ()):
-                    try:
-                        # this will do the right thing when dep is absolute too
-                        deppath = path.join(self.srcdir, dep)
-                        if not path.isfile(deppath):
-                            changed.add(docname)
-                            break
-                        depmtime = path.getmtime(deppath)
-                        if depmtime > mtime:
-                            changed.add(docname)
-                            break
-                    except EnvironmentError:
-                        # give it another chance
-                        changed.add(docname)
-                        break
-
-        return added, changed, removed
-
-    def update(self, config, srcdir, doctreedir, app=None):
-        """(Re-)read all files new or changed since last update.
-
-        Returns a summary, the total count of documents to reread and an
-        iterator that yields docnames as it processes them.  Store all
-        environment docnames in the canonical format (ie using SEP as a
-        separator in place of os.path.sep).
-        """
-        config_changed = False
-        if self.config is None:
-            msg = '[new config] '
-            config_changed = True
-        else:
-            # check if a config value was changed that affects how
-            # doctrees are read
-            for key, descr in config.values.iteritems():
-                if descr[1] != 'env':
-                    continue
-                if self.config[key] != config[key]:
-                    msg = '[config changed] '
-                    config_changed = True
-                    break
-            else:
-                msg = ''
-            # this value is not covered by the above loop because it is handled
-            # specially by the config class
-            if self.config.extensions != config.extensions:
-                msg = '[extensions changed] '
-                config_changed = True
-        # the source and doctree directories may have been relocated
-        self.srcdir = srcdir
-        self.doctreedir = doctreedir
-        self.find_files(config)
-        self.config = config
-
-        added, changed, removed = self.get_outdated_files(config_changed)
-
-        # allow user intervention as well
-        for docs in app.emit('env-get-outdated', self, added, changed, removed):
-            changed.update(set(docs) & self.found_docs)
-
-        # if files were added or removed, all documents with globbed toctrees
-        # must be reread
-        if added or removed:
-            # ... but not those that already were removed
-            changed.update(self.glob_toctrees & self.found_docs)
-
-        msg += '%s added, %s changed, %s removed' % (len(added), len(changed),
-                                                     len(removed))
-
-        def update_generator():
-            self.app = app
-
-            # clear all files no longer present
-            for docname in removed:
-                if app:
-                    app.emit('env-purge-doc', self, docname)
-                self.clear_doc(docname)
-
-            # read all new and changed files
-            for docname in sorted(added | changed):
-                yield docname
-                self.read_doc(docname, app=app)
-
-            if config.master_doc not in self.all_docs:
-                self.warn(None, 'master file %s not found' %
-                          self.doc2path(config.master_doc))
-
-            self.app = None
-            if app:
-                app.emit('env-updated', self)
-
-        return msg, len(added | changed), update_generator()
-
-    def check_dependents(self, already):
-        to_rewrite = self.assign_section_numbers()
-        for docname in to_rewrite:
-            if docname not in already:
-                yield docname
-
-    # --------- SINGLE FILE READING --------------------------------------------
-
-    def warn_and_replace(self, error):
-        """Custom decoding error handler that warns and replaces."""
-        linestart = error.object.rfind('\n', 0, error.start)
-        lineend = error.object.find('\n', error.start)
-        if lineend == -1: lineend = len(error.object)
-        lineno = error.object.count('\n', 0, error.start) + 1
-        self.warn(self.docname, 'undecodable source characters, '
-                  'replacing with "?": %r' %
-                  (error.object[linestart+1:error.start] + '>>>' +
-                   error.object[error.start:error.end] + '<<<' +
-                   error.object[error.end:lineend]), lineno)
-        return (u'?', error.end)
-
-    def lookup_domain_element(self, type, name):
-        """Lookup a markup element (directive or role), given its name which can
-        be a full name (with domain).
-        """
-        name = name.lower()
-        # explicit domain given?
-        if ':' in name:
-            domain_name, name = name.split(':', 1)
-            if domain_name in self.domains:
-                domain = self.domains[domain_name]
-                element = getattr(domain, type)(name)
-                if element is not None:
-                    return element, []
-        # else look in the default domain
-        else:
-            def_domain = self.temp_data.get('default_domain')
-            if def_domain is not None:
-                element = getattr(def_domain, type)(name)
-                if element is not None:
-                    return element, []
-        # always look in the std domain
-        element = getattr(self.domains['std'], type)(name)
-        if element is not None:
-            return element, []
-        raise ElementLookupError
-
-    def patch_lookup_functions(self):
-        """Monkey-patch directive and role dispatch, so that domain-specific
-        markup takes precedence.
-        """
-        def directive(name, lang_module, document):
-            try:
-                return self.lookup_domain_element('directive', name)
-            except ElementLookupError:
-                return orig_directive_function(name, lang_module, document)
-
-        def role(name, lang_module, lineno, reporter):
-            try:
-                return self.lookup_domain_element('role', name)
-            except ElementLookupError:
-                return orig_role_function(name, lang_module, lineno, reporter)
-
-        directives.directive = directive
-        roles.role = role
-
-    def read_doc(self, docname, src_path=None, save_parsed=True, app=None):
-        """Parse a file and add/update inventory entries for the doctree.
-
-        If srcpath is given, read from a different source file.
-        """
-        # remove all inventory entries for that file
-        if app:
-            app.emit('env-purge-doc', self, docname)
-
-        self.clear_doc(docname)
-
-        if src_path is None:
-            src_path = self.doc2path(docname)
-
-        self.temp_data['docname'] = docname
-        # defaults to the global default, but can be re-set in a document
-        self.temp_data['default_domain'] = \
-            self.domains.get(self.config.primary_domain)
-
-        self.settings['input_encoding'] = self.config.source_encoding
-        self.settings['trim_footnote_reference_space'] = \
-            self.config.trim_footnote_reference_space
-        self.settings['gettext_compact'] = self.config.gettext_compact
-
-        self.patch_lookup_functions()
-
-        if self.config.default_role:
-            role_fn, messages = roles.role(self.config.default_role, english,
-                                           0, dummy_reporter)
-            if role_fn:
-                roles._roles[''] = role_fn
-            else:
-                self.warn(docname, 'default role %s not found' %
-                          self.config.default_role)
-
-        codecs.register_error('sphinx', self.warn_and_replace)
-
-        class SphinxSourceClass(FileInput):
-            def __init__(self_, *args, **kwds):
-                # don't call sys.exit() on IOErrors
-                kwds['handle_io_errors'] = False
-                FileInput.__init__(self_, *args, **kwds)
-
-            def decode(self_, data):
-                if isinstance(data, unicode):
-                    return data
-                return data.decode(self_.encoding, 'sphinx')
-
-            def read(self_):
-                data = FileInput.read(self_)
-                if app:
-                    arg = [data]
-                    app.emit('source-read', docname, arg)
-                    data = arg[0]
-                if self.config.rst_epilog:
-                    data = data + '\n' + self.config.rst_epilog + '\n'
-                if self.config.rst_prolog:
-                    data = self.config.rst_prolog + '\n' + data
-                return data
-
-        # publish manually
-        pub = Publisher(reader=SphinxStandaloneReader(),
-                        writer=SphinxDummyWriter(),
-                        source_class=SphinxSourceClass,
-                        destination_class=NullOutput)
-        pub.set_components(None, 'restructuredtext', None)
-        pub.process_programmatic_settings(None, self.settings, None)
-        pub.set_source(None, src_path.encode(fs_encoding))
-        pub.set_destination(None, None)
-        try:
-            pub.publish()
-            doctree = pub.document
-        except UnicodeError, err:
-            raise SphinxError(str(err))
-
-        # post-processing
-        self.filter_messages(doctree)
-        self.process_dependencies(docname, doctree)
-        self.process_images(docname, doctree)
-        self.process_downloads(docname, doctree)
-        self.process_metadata(docname, doctree)
-        self.process_refonly_bullet_lists(docname, doctree)
-        self.create_title_from(docname, doctree)
-        self.note_indexentries_from(docname, doctree)
-        self.note_citations_from(docname, doctree)
-        self.build_toc_from(docname, doctree)
-        for domain in self.domains.itervalues():
-            domain.process_doc(self, docname, doctree)
-
-        # allow extension-specific post-processing
-        if app:
-            app.emit('doctree-read', doctree)
-
-        # store time of build, for outdated files detection
-        self.all_docs[docname] = time.time()
-
-        if self.versioning_condition:
-            # get old doctree
-            try:
-                f = open(self.doc2path(docname,
-                                       self.doctreedir, '.doctree'), 'rb')
-                try:
-                    old_doctree = pickle.load(f)
-                finally:
-                    f.close()
-            except EnvironmentError:
-                old_doctree = None
-
-            # add uids for versioning
-            if old_doctree is None:
-                list(add_uids(doctree, self.versioning_condition))
-            else:
-                list(merge_doctrees(
-                    old_doctree, doctree, self.versioning_condition))
-
-        # make it picklable
-        doctree.reporter = None
-        doctree.transformer = None
-        doctree.settings.warning_stream = None
-        doctree.settings.env = None
-        doctree.settings.record_dependencies = None
-        for metanode in doctree.traverse(MetaBody.meta):
-            # docutils' meta nodes aren't picklable because the class is nested
-            metanode.__class__ = addnodes.meta
-
-        # cleanup
-        self.temp_data.clear()
-
-        if save_parsed:
-            # save the parsed doctree
-            doctree_filename = self.doc2path(docname, self.doctreedir,
-                                             '.doctree')
-            dirname = path.dirname(doctree_filename)
-            if not path.isdir(dirname):
-                os.makedirs(dirname)
-            f = open(doctree_filename, 'wb')
-            try:
-                pickle.dump(doctree, f, pickle.HIGHEST_PROTOCOL)
-            finally:
-                f.close()
-        else:
-            return doctree
-
-    # utilities to use while reading a document
-
-    @property
-    def docname(self):
-        """Backwards compatible alias."""
-        return self.temp_data['docname']
-
-    @property
-    def currmodule(self):
-        """Backwards compatible alias."""
-        return self.temp_data.get('py:module')
-
-    @property
-    def currclass(self):
-        """Backwards compatible alias."""
-        return self.temp_data.get('py:class')
-
-    def new_serialno(self, category=''):
-        """Return a serial number, e.g. for index entry targets."""
-        key = category + 'serialno'
-        cur = self.temp_data.get(key, 0)
-        self.temp_data[key] = cur + 1
-        return cur
-
-    def note_dependency(self, filename):
-        self.dependencies.setdefault(self.docname, set()).add(filename)
-
-    def note_reread(self):
-        self.reread_always.add(self.docname)
-
-    def note_versionchange(self, type, version, node, lineno):
-        self.versionchanges.setdefault(version, []).append(
-            (type, self.temp_data['docname'], lineno,
-             self.temp_data.get('py:module'),
-             self.temp_data.get('object'), node.astext()))
-
-    # post-processing of read doctrees
-
-    def filter_messages(self, doctree):
-        """Filter system messages from a doctree."""
-        filterlevel = self.config.keep_warnings and 2 or 5
-        for node in doctree.traverse(nodes.system_message):
-            if node['level'] < filterlevel:
-                node.parent.remove(node)
-
-
-    def process_dependencies(self, docname, doctree):
-        """Process docutils-generated dependency info."""
-        cwd = os.getcwd()
-        frompath = path.join(path.normpath(self.srcdir), 'dummy')
-        deps = doctree.settings.record_dependencies
-        if not deps:
-            return
-        for dep in deps.list:
-            # the dependency path is relative to the working dir, so get
-            # one relative to the srcdir
-            relpath = relative_path(frompath,
-                                    path.normpath(path.join(cwd, dep)))
-            self.dependencies.setdefault(docname, set()).add(relpath)
-
-    def process_downloads(self, docname, doctree):
-        """Process downloadable file paths. """
-        for node in doctree.traverse(addnodes.download_reference):
-            targetname = node['reftarget']
-            rel_filename, filename = self.relfn2path(targetname, docname)
-            self.dependencies.setdefault(docname, set()).add(rel_filename)
-            if not os.access(filename, os.R_OK):
-                self.warn_node('download file not readable: %s' % filename,
-                               node)
-                continue
-            uniquename = self.dlfiles.add_file(docname, filename)
-            node['filename'] = uniquename
-
-    def process_images(self, docname, doctree):
-        """Process and rewrite image URIs."""
-        for node in doctree.traverse(nodes.image):
-            # Map the mimetype to the corresponding image.  The writer may
-            # choose the best image from these candidates.  The special key * is
-            # set if there is only single candidate to be used by a writer.
-            # The special key ? is set for nonlocal URIs.
-            node['candidates'] = candidates = {}
-            imguri = node['uri']
-            if imguri.find('://') != -1:
-                self.warn_node('nonlocal image URI found: %s' % imguri, node)
-                candidates['?'] = imguri
-                continue
-            rel_imgpath, full_imgpath = self.relfn2path(imguri, docname)
-            # set imgpath as default URI
-            node['uri'] = rel_imgpath
-            if rel_imgpath.endswith(os.extsep + '*'):
-                for filename in glob(full_imgpath):
-                    new_imgpath = relative_path(self.srcdir, filename)
-                    if filename.lower().endswith('.pdf'):
-                        candidates['application/pdf'] = new_imgpath
-                    elif filename.lower().endswith('.svg'):
-                        candidates['image/svg+xml'] = new_imgpath
-                    else:
-                        try:
-                            f = open(filename, 'rb')
-                            try:
-                                imgtype = imghdr.what(f)
-                            finally:
-                                f.close()
-                        except (OSError, IOError), err:
-                            self.warn_node('image file %s not readable: %s' %
-                                           (filename, err), node)
-                        if imgtype:
-                            candidates['image/' + imgtype] = new_imgpath
-            else:
-                candidates['*'] = rel_imgpath
-            # map image paths to unique image names (so that they can be put
-            # into a single directory)
-            for imgpath in candidates.itervalues():
-                self.dependencies.setdefault(docname, set()).add(imgpath)
-                if not os.access(path.join(self.srcdir, imgpath), os.R_OK):
-                    self.warn_node('image file not readable: %s' % imgpath,
-                                   node)
-                    continue
-                self.images.add_file(docname, imgpath)
-
-    def process_metadata(self, docname, doctree):
-        """Process the docinfo part of the doctree as metadata.
-
-        Keep processing minimal -- just return what docutils says.
-        """
-        self.metadata[docname] = md = {}
-        try:
-            docinfo = doctree[0]
-        except IndexError:
-            # probably an empty document
-            return
-        if docinfo.__class__ is not nodes.docinfo:
-            # nothing to see here
-            return
-        for node in docinfo:
-            # nodes are multiply inherited...
-            if isinstance(node, nodes.authors):
-                md['authors'] = [author.astext() for author in node]
-            elif isinstance(node, nodes.TextElement): # e.g. author
-                md[node.__class__.__name__] = node.astext()
-            else:
-                name, body = node
-                md[name.astext()] = body.astext()
-        del doctree[0]
-
-    def process_refonly_bullet_lists(self, docname, doctree):
-        """Change refonly bullet lists to use compact_paragraphs.
-
-        Specifically implemented for 'Indices and Tables' section, which looks
-        odd when html_compact_lists is false.
-        """
-        if self.config.html_compact_lists:
-            return
-
-        class RefOnlyListChecker(nodes.GenericNodeVisitor):
-            """Raise `nodes.NodeFound` if non-simple list item is encountered.
-
-            Here 'simple' means a list item containing only a paragraph with a
-            single reference in it.
-            """
-
-            def default_visit(self, node):
-                raise nodes.NodeFound
-
-            def visit_bullet_list(self, node):
-                pass
-
-            def visit_list_item(self, node):
-                children = []
-                for child in node.children:
-                    if not isinstance(child, nodes.Invisible):
-                        children.append(child)
-                if len(children) != 1:
-                    raise nodes.NodeFound
-                if not isinstance(children[0], nodes.paragraph):
-                    raise nodes.NodeFound
-                para = children[0]
-                if len(para) != 1:
-                    raise nodes.NodeFound
-                if not isinstance(para[0], addnodes.pending_xref):
-                    raise nodes.NodeFound
-                raise nodes.SkipChildren
-
-            def invisible_visit(self, node):
-                """Invisible nodes should be ignored."""
-                pass
-
-        def check_refonly_list(node):
-            """Check for list with only references in it."""
-            visitor = RefOnlyListChecker(doctree)
-            try:
-                node.walk(visitor)
-            except nodes.NodeFound:
-                return False
-            else:
-                return True
-
-        for node in doctree.traverse(nodes.bullet_list):
-            if check_refonly_list(node):
-                for item in node.traverse(nodes.list_item):
-                    para = item[0]
-                    ref = para[0]
-                    compact_para = addnodes.compact_paragraph()
-                    compact_para += ref
-                    item.replace(para, compact_para)
-
-    def create_title_from(self, docname, document):
-        """Add a title node to the document (just copy the first section title),
-        and store that title in the environment.
-        """
-        titlenode = nodes.title()
-        longtitlenode = titlenode
-        # explicit title set with title directive; use this only for
-        # the <title> tag in HTML output
-        if document.has_key('title'):
-            longtitlenode = nodes.title()
-            longtitlenode += nodes.Text(document['title'])
-        # look for first section title and use that as the title
-        for node in document.traverse(nodes.section):
-            visitor = SphinxContentsFilter(document)
-            node[0].walkabout(visitor)
-            titlenode += visitor.get_entry_text()
-            break
-        else:
-            # document has no title
-            titlenode += nodes.Text('<no title>')
-        self.titles[docname] = titlenode
-        self.longtitles[docname] = longtitlenode
-
-    def note_indexentries_from(self, docname, document):
-        entries = self.indexentries[docname] = []
-        for node in document.traverse(addnodes.index):
-            entries.extend(node['entries'])
-
-    def note_citations_from(self, docname, document):
-        for node in document.traverse(nodes.citation):
-            label = node[0].astext()
-            if label in self.citations:
-                self.warn_node('duplicate citation %s, ' % label +
-                               'other instance in %s' % self.doc2path(
-                                   self.citations[label][0]), node)
-            self.citations[label] = (docname, node['ids'][0])
-
-    def note_toctree(self, docname, toctreenode):
-        """Note a TOC tree directive in a document and gather information about
-        file relations from it.
-        """
-        if toctreenode['glob']:
-            self.glob_toctrees.add(docname)
-        if toctreenode.get('numbered'):
-            self.numbered_toctrees.add(docname)
-        includefiles = toctreenode['includefiles']
-        for includefile in includefiles:
-            # note that if the included file is rebuilt, this one must be
-            # too (since the TOC of the included file could have changed)
-            self.files_to_rebuild.setdefault(includefile, set()).add(docname)
-        self.toctree_includes.setdefault(docname, []).extend(includefiles)
-
-    def build_toc_from(self, docname, document):
-        """Build a TOC from the doctree and store it in the inventory."""
-        numentries = [0] # nonlocal again...
-
-        try:
-            maxdepth = int(self.metadata[docname].get('tocdepth', 0))
-        except ValueError:
-            maxdepth = 0
-
-        def traverse_in_section(node, cls):
-            """Like traverse(), but stay within the same section."""
-            result = []
-            if isinstance(node, cls):
-                result.append(node)
-            for child in node.children:
-                if isinstance(child, nodes.section):
-                    continue
-                result.extend(traverse_in_section(child, cls))
-            return result
-
-        def build_toc(node, depth=1):
-            entries = []
-            for sectionnode in node:
-                # find all toctree nodes in this section and add them
-                # to the toc (just copying the toctree node which is then
-                # resolved in self.get_and_resolve_doctree)
-                if isinstance(sectionnode, addnodes.only):
-                    onlynode = addnodes.only(expr=sectionnode['expr'])
-                    blist = build_toc(sectionnode, depth)
-                    if blist:
-                        onlynode += blist.children
-                        entries.append(onlynode)
-                if not isinstance(sectionnode, nodes.section):
-                    for toctreenode in traverse_in_section(sectionnode,
-                                                           addnodes.toctree):
-                        item = toctreenode.copy()
-                        entries.append(item)
-                        # important: do the inventory stuff
-                        self.note_toctree(docname, toctreenode)
-                    continue
-                title = sectionnode[0]
-                # copy the contents of the section title, but without references
-                # and unnecessary stuff
-                visitor = SphinxContentsFilter(document)
-                title.walkabout(visitor)
-                nodetext = visitor.get_entry_text()
-                if not numentries[0]:
-                    # for the very first toc entry, don't add an anchor
-                    # as it is the file's title anyway
-                    anchorname = ''
-                else:
-                    anchorname = '#' + sectionnode['ids'][0]
-                numentries[0] += 1
-                # make these nodes:
-                # list_item -> compact_paragraph -> reference
-                reference = nodes.reference(
-                    '', '', internal=True, refuri=docname,
-                    anchorname=anchorname, *nodetext)
-                para = addnodes.compact_paragraph('', '', reference)
-                item = nodes.list_item('', para)
-                if maxdepth == 0 or depth < maxdepth:
-                    item += build_toc(sectionnode, depth+1)
-                entries.append(item)
-            if entries:
-                return nodes.bullet_list('', *entries)
-            return []
-        toc = build_toc(document)
-        if toc:
-            self.tocs[docname] = toc
-        else:
-            self.tocs[docname] = nodes.bullet_list('')
-        self.toc_num_entries[docname] = numentries[0]
-
-    def get_toc_for(self, docname, builder):
-        """Return a TOC nodetree -- for use on the same page only!"""
-        try:
-            toc = self.tocs[docname].deepcopy()
-        except KeyError:
-            # the document does not exist anymore: return a dummy node that
-            # renders to nothing
-            return nodes.paragraph()
-        self.process_only_nodes(toc, builder, docname)
-        for node in toc.traverse(nodes.reference):
-            node['refuri'] = node['anchorname'] or '#'
-        return toc
-
-    def get_toctree_for(self, docname, builder, collapse, **kwds):
-        """Return the global TOC nodetree."""
-        doctree = self.get_doctree(self.config.master_doc)
-        toctrees = []
-        if 'includehidden' not in kwds:
-            kwds['includehidden'] = True
-        if 'maxdepth' not in kwds:
-            kwds['maxdepth'] = 0
-        kwds['collapse'] = collapse
-        for toctreenode in doctree.traverse(addnodes.toctree):
-            toctree = self.resolve_toctree(docname, builder, toctreenode,
-                                           prune=True, **kwds)
-            toctrees.append(toctree)
-        if not toctrees:
-            return None
-        result = toctrees[0]
-        for toctree in toctrees[1:]:
-            result.extend(toctree.children)
-        return result
-
-    def get_domain(self, domainname):
-        """Return the domain instance with the specified name.
-
-        Raises an ExtensionError if the domain is not registered.
-        """
-        try:
-            return self.domains[domainname]
-        except KeyError:
-            raise ExtensionError('Domain %r is not registered' % domainname)
-
-    # --------- RESOLVING REFERENCES AND TOCTREES ------------------------------
-
-    def get_doctree(self, docname):
-        """Read the doctree for a file from the pickle and return it."""
-        doctree_filename = self.doc2path(docname, self.doctreedir, '.doctree')
-        f = open(doctree_filename, 'rb')
-        try:
-            doctree = pickle.load(f)
-        finally:
-            f.close()
-        doctree.settings.env = self
-        doctree.reporter = Reporter(self.doc2path(docname), 2, 5,
-                                    stream=WarningStream(self._warnfunc))
-        return doctree
-
-
-    def get_and_resolve_doctree(self, docname, builder, doctree=None,
-                                prune_toctrees=True):
-        """Read the doctree from the pickle, resolve cross-references and
-        toctrees and return it.
-        """
-        if doctree is None:
-            doctree = self.get_doctree(docname)
-
-        # resolve all pending cross-references
-        self.resolve_references(doctree, docname, builder)
-
-        # now, resolve all toctree nodes
-        for toctreenode in doctree.traverse(addnodes.toctree):
-            result = self.resolve_toctree(docname, builder, toctreenode,
-                                          prune=prune_toctrees)
-            if result is None:
-                toctreenode.replace_self([])
-            else:
-                toctreenode.replace_self(result)
-
-        return doctree
-
-    def resolve_toctree(self, docname, builder, toctree, prune=True, maxdepth=0,
-                        titles_only=False, collapse=False, includehidden=False):
-        """Resolve a *toctree* node into individual bullet lists with titles
-        as items, returning None (if no containing titles are found) or
-        a new node.
-
-        If *prune* is True, the tree is pruned to *maxdepth*, or if that is 0,
-        to the value of the *maxdepth* option on the *toctree* node.
-        If *titles_only* is True, only toplevel document titles will be in the
-        resulting tree.
-        If *collapse* is True, all branches not containing docname will
-        be collapsed.
-        """
-        if toctree.get('hidden', False) and not includehidden:
-            return None
-
-        def _walk_depth(node, depth, maxdepth):
-            """Utility: Cut a TOC at a specified depth."""
-
-            # For reading this function, it is useful to keep in mind the node
-            # structure of a toctree (using HTML-like node names for brevity):
-            #
-            # <ul>
-            #   <li>
-            #     <p><a></p>
-            #     <p><a></p>
-            #     ...
-            #     <ul>
-            #       ...
-            #     </ul>
-            #   </li>
-            # </ul>
-
-            for subnode in node.children[:]:
-                if isinstance(subnode, (addnodes.compact_paragraph,
-                                        nodes.list_item)):
-                    # for <p> and <li>, just indicate the depth level and
-                    # recurse to children
-                    subnode['classes'].append('toctree-l%d' % (depth-1))
-                    _walk_depth(subnode, depth, maxdepth)
-
-                elif isinstance(subnode, nodes.bullet_list):
-                    # for <ul>, determine if the depth is too large or if the
-                    # entry is to be collapsed
-                    if maxdepth > 0 and depth > maxdepth:
-                        subnode.parent.replace(subnode, [])
-                    else:
-                        # to find out what to collapse, *first* walk subitems,
-                        # since that determines which children point to the
-                        # current page
-                        _walk_depth(subnode, depth+1, maxdepth)
-                        # cull sub-entries whose parents aren't 'current'
-                        if (collapse and depth > 1 and
-                            'iscurrent' not in subnode.parent):
-                            subnode.parent.remove(subnode)
-
-                elif isinstance(subnode, nodes.reference):
-                    # for <a>, identify which entries point to the current
-                    # document and therefore may not be collapsed
-                    if subnode['refuri'] == docname:
-                        if not subnode['anchorname']:
-                            # give the whole branch a 'current' class
-                            # (useful for styling it differently)
-                            branchnode = subnode
-                            while branchnode:
-                                branchnode['classes'].append('current')
-                                branchnode = branchnode.parent
-                        # mark the list_item as "on current page"
-                        if subnode.parent.parent.get('iscurrent'):
-                            # but only if it's not already done
-                            return
-                        while subnode:
-                            subnode['iscurrent'] = True
-                            subnode = subnode.parent
-
-        def _entries_from_toctree(toctreenode, parents,
-                                  separate=False, subtree=False):
-            """Return TOC entries for a toctree node."""
-            refs = [(e[0], str(e[1])) for e in toctreenode['entries']]
-            entries = []
-            for (title, ref) in refs:
-                try:
-                    refdoc = None
-                    if url_re.match(ref):
-                        reference = nodes.reference('', '', internal=False,
-                                                    refuri=ref, anchorname='',
-                                                    *[nodes.Text(title)])
-                        para = addnodes.compact_paragraph('', '', reference)
-                        item = nodes.list_item('', para)
-                        toc = nodes.bullet_list('', item)
-                    elif ref == 'self':
-                        # 'self' refers to the document from which this
-                        # toctree originates
-                        ref = toctreenode['parent']
-                        if not title:
-                            title = clean_astext(self.titles[ref])
-                        reference = nodes.reference('', '', internal=True,
-                                                    refuri=ref,
-                                                    anchorname='',
-                                                    *[nodes.Text(title)])
-                        para = addnodes.compact_paragraph('', '', reference)
-                        item = nodes.list_item('', para)
-                        # don't show subitems
-                        toc = nodes.bullet_list('', item)
-                    else:
-                        if ref in parents:
-                            self.warn(ref, 'circular toctree references '
-                                      'detected, ignoring: %s <- %s' %
-                                      (ref, ' <- '.join(parents)))
-                            continue
-                        refdoc = ref
-                        toc = self.tocs[ref].deepcopy()
-                        self.process_only_nodes(toc, builder, ref)
-                        if title and toc.children and len(toc.children) == 1:
-                            child = toc.children[0]
-                            for refnode in child.traverse(nodes.reference):
-                                if refnode['refuri'] == ref and \
-                                       not refnode['anchorname']:
-                                    refnode.children = [nodes.Text(title)]
-                    if not toc.children:
-                        # empty toc means: no titles will show up in the toctree
-                        self.warn_node(
-                            'toctree contains reference to document %r that '
-                            'doesn\'t have a title: no link will be generated'
-                            % ref, toctreenode)
-                except KeyError:
-                    # this is raised if the included file does not exist
-                    self.warn_node(
-                        'toctree contains reference to nonexisting document %r'
-                        % ref, toctreenode)
-                else:
-                    # if titles_only is given, only keep the main title and
-                    # sub-toctrees
-                    if titles_only:
-                        # delete everything but the toplevel title(s)
-                        # and toctrees
-                        for toplevel in toc:
-                            # nodes with length 1 don't have any children anyway
-                            if len(toplevel) > 1:
-                                subtrees = toplevel.traverse(addnodes.toctree)
-                                toplevel[1][:] = subtrees
-                    # resolve all sub-toctrees
-                    for toctreenode in toc.traverse(addnodes.toctree):
-                        if not (toctreenode.get('hidden', False)
-                                and not includehidden):
-                            i = toctreenode.parent.index(toctreenode) + 1
-                            for item in _entries_from_toctree(
-                                    toctreenode, [refdoc] + parents,
-                                    subtree=True):
-                                toctreenode.parent.insert(i, item)
-                                i += 1
-                            toctreenode.parent.remove(toctreenode)
-                    if separate:
-                        entries.append(toc)
-                    else:
-                        entries.extend(toc.children)
-            if not subtree and not separate:
-                ret = nodes.bullet_list()
-                ret += entries
-                return [ret]
-            return entries
-
-        maxdepth = maxdepth or toctree.get('maxdepth', -1)
-        if not titles_only and toctree.get('titlesonly', False):
-            titles_only = True
-
-        # NOTE: previously, this was separate=True, but that leads to artificial
-        # separation when two or more toctree entries form a logical unit, so
-        # separating mode is no longer used -- it's kept here for history's sake
-        tocentries = _entries_from_toctree(toctree, [], separate=False)
-        if not tocentries:
-            return None
-
-        newnode = addnodes.compact_paragraph('', '', *tocentries)
-        newnode['toctree'] = True
-
-        # prune the tree to maxdepth and replace titles, also set level classes
-        _walk_depth(newnode, 1, prune and maxdepth or 0)
-
-        # set the target paths in the toctrees (they are not known at TOC
-        # generation time)
-        for refnode in newnode.traverse(nodes.reference):
-            if not url_re.match(refnode['refuri']):
-                refnode['refuri'] = builder.get_relative_uri(
-                    docname, refnode['refuri']) + refnode['anchorname']
-        return newnode
-
-    def resolve_references(self, doctree, fromdocname, builder):
-        for node in doctree.traverse(addnodes.pending_xref):
-            contnode = node[0].deepcopy()
-            newnode = None
-
-            typ = node['reftype']
-            target = node['reftarget']
-            refdoc = node.get('refdoc', fromdocname)
-            domain = None
-
-            try:
-                if 'refdomain' in node and node['refdomain']:
-                    # let the domain try to resolve the reference
-                    try:
-                        domain = self.domains[node['refdomain']]
-                    except KeyError:
-                        raise NoUri
-                    newnode = domain.resolve_xref(self, fromdocname, builder,
-                                                  typ, target, node, contnode)
-                # really hardwired reference types
-                elif typ == 'doc':
-                    # directly reference to document by source name;
-                    # can be absolute or relative
-                    docname = docname_join(refdoc, target)
-                    if docname in self.all_docs:
-                        if node['refexplicit']:
-                            # reference with explicit title
-                            caption = node.astext()
-                        else:
-                            caption = clean_astext(self.titles[docname])
-                        innernode = nodes.emphasis(caption, caption)
-                        newnode = nodes.reference('', '', internal=True)
-                        newnode['refuri'] = builder.get_relative_uri(
-                            fromdocname, docname)
-                        newnode.append(innernode)
-                elif typ == 'citation':
-                    docname, labelid = self.citations.get(target, ('', ''))
-                    if docname:
-                        newnode = make_refnode(builder, fromdocname, docname,
-                                               labelid, contnode)
-                # no new node found? try the missing-reference event
-                if newnode is None:
-                    newnode = builder.app.emit_firstresult(
-                        'missing-reference', self, node, contnode)
-                    # still not found? warn if in nit-picky mode
-                    if newnode is None:
-                        self._warn_missing_reference(
-                            fromdocname, typ, target, node, domain)
-            except NoUri:
-                newnode = contnode
-            node.replace_self(newnode or contnode)
-
-        # remove only-nodes that do not belong to our builder
-        self.process_only_nodes(doctree, builder, fromdocname)
-
-        # allow custom references to be resolved
-        builder.app.emit('doctree-resolved', doctree, fromdocname)
-
-    def _warn_missing_reference(self, fromdoc, typ, target, node, domain):
-        warn = node.get('refwarn')
-        if self.config.nitpicky:
-            warn = True
-            if self._nitpick_ignore:
-                dtype = domain and '%s:%s' % (domain.name, typ) or typ
-                if (dtype, target) in self._nitpick_ignore:
-                    warn = False
-        if not warn:
-            return
-        if domain and typ in domain.dangling_warnings:
-            msg = domain.dangling_warnings[typ]
-        elif typ == 'doc':
-            msg = 'unknown document: %(target)s'
-        elif typ == 'citation':
-            msg = 'citation not found: %(target)s'
-        elif node.get('refdomain', 'std') != 'std':
-            msg = '%s:%s reference target not found: %%(target)s' % \
-                  (node['refdomain'], typ)
-        else:
-            msg = '%s reference target not found: %%(target)s' % typ
-        self.warn_node(msg % {'target': target}, node)
-
-    def process_only_nodes(self, doctree, builder, fromdocname=None):
-        # A comment on the comment() nodes being inserted: replacing by [] would
-        # result in a "Losing ids" exception if there is a target node before
-        # the only node, so we make sure docutils can transfer the id to
-        # something, even if it's just a comment and will lose the id anyway...
-        for node in doctree.traverse(addnodes.only):
-            try:
-                ret = builder.tags.eval_condition(node['expr'])
-            except Exception, err:
-                self.warn_node('exception while evaluating only '
-                               'directive expression: %s' % err, node)
-                node.replace_self(node.children or nodes.comment())
-            else:
-                if ret:
-                    node.replace_self(node.children or nodes.comment())
-                else:
-                    node.replace_self(nodes.comment())
-
-    def assign_section_numbers(self):
-        """Assign a section number to each heading under a numbered toctree."""
-        # a list of all docnames whose section numbers changed
-        rewrite_needed = []
-
-        old_secnumbers = self.toc_secnumbers
-        self.toc_secnumbers = {}
-
-        def _walk_toc(node, secnums, depth, titlenode=None):
-            # titlenode is the title of the document, it will get assigned a
-            # secnumber too, so that it shows up in next/prev/parent rellinks
-            for subnode in node.children:
-                if isinstance(subnode, nodes.bullet_list):
-                    numstack.append(0)
-                    _walk_toc(subnode, secnums, depth-1, titlenode)
-                    numstack.pop()
-                    titlenode = None
-                elif isinstance(subnode, nodes.list_item):
-                    _walk_toc(subnode, secnums, depth, titlenode)
-                    titlenode = None
-                elif isinstance(subnode, addnodes.only):
-                    # at this stage we don't know yet which sections are going
-                    # to be included; just include all of them, even if it leads
-                    # to gaps in the numbering
-                    _walk_toc(subnode, secnums, depth, titlenode)
-                    titlenode = None
-                elif isinstance(subnode, addnodes.compact_paragraph):
-                    numstack[-1] += 1
-                    if depth > 0:
-                        number = tuple(numstack)
-                    else:
-                        number = None
-                    secnums[subnode[0]['anchorname']] = \
-                        subnode[0]['secnumber'] = number
-                    if titlenode:
-                        titlenode['secnumber'] = number
-                        titlenode = None
-                elif isinstance(subnode, addnodes.toctree):
-                    _walk_toctree(subnode, depth)
-
-        def _walk_toctree(toctreenode, depth):
-            if depth == 0:
-                return
-            for (title, ref) in toctreenode['entries']:
-                if url_re.match(ref) or ref == 'self':
-                    # don't mess with those
-                    continue
-                if ref in self.tocs:
-                    secnums = self.toc_secnumbers[ref] = {}
-                    _walk_toc(self.tocs[ref], secnums, depth,
-                              self.titles.get(ref))
-                    if secnums != old_secnumbers.get(ref):
-                        rewrite_needed.append(ref)
-
-        for docname in self.numbered_toctrees:
-            doctree = self.get_doctree(docname)
-            for toctreenode in doctree.traverse(addnodes.toctree):
-                depth = toctreenode.get('numbered', 0)
-                if depth:
-                    # every numbered toctree gets new numbering
-                    numstack = [0]
-                    _walk_toctree(toctreenode, depth)
-
-        return rewrite_needed
-
-    def create_index(self, builder, group_entries=True,
-                     _fixre=re.compile(r'(.*) ([(][^()]*[)])')):
-        """Create the real index from the collected index entries."""
-        new = {}
-
-        def add_entry(word, subword, link=True, dic=new):
-            entry = dic.get(word)
-            if not entry:
-                dic[word] = entry = [[], {}]
-            if subword:
-                add_entry(subword, '', link=link, dic=entry[1])
-            elif link:
-                try:
-                    uri = builder.get_relative_uri('genindex', fn) + '#' + tid
-                except NoUri:
-                    pass
-                else:
-                    entry[0].append((main, uri))
-
-        for fn, entries in self.indexentries.iteritems():
-            # new entry types must be listed in directives/other.py!
-            for type, value, tid, main in entries:
-                try:
-                    if type == 'single':
-                        try:
-                            entry, subentry = split_into(2, 'single', value)
-                        except ValueError:
-                            entry, = split_into(1, 'single', value)
-                            subentry = ''
-                        add_entry(entry, subentry)
-                    elif type == 'pair':
-                        first, second = split_into(2, 'pair', value)
-                        add_entry(first, second)
-                        add_entry(second, first)
-                    elif type == 'triple':
-                        first, second, third = split_into(3, 'triple', value)
-                        add_entry(first, second+' '+third)
-                        add_entry(second, third+', '+first)
-                        add_entry(third, first+' '+second)
-                    elif type == 'see':
-                        first, second = split_into(2, 'see', value)
-                        add_entry(first, _('see %s') % second, link=False)
-                    elif type == 'seealso':
-                        first, second = split_into(2, 'see', value)
-                        add_entry(first, _('see also %s') % second, link=False)
-                    else:
-                        self.warn(fn, 'unknown index entry type %r' % type)
-                except ValueError, err:
-                    self.warn(fn, str(err))
-
-        # sort the index entries; put all symbols at the front, even those
-        # following the letters in ASCII, this is where the chr(127) comes from
-        def keyfunc(entry, lcletters=string.ascii_lowercase + '_'):
-            lckey = unicodedata.normalize('NFD', entry[0].lower())
-            if lckey[0:1] in lcletters:
-                return chr(127) + lckey
-            return lckey
-        newlist = new.items()
-        newlist.sort(key=keyfunc)
-
-        if group_entries:
-            # fixup entries: transform
-            #   func() (in module foo)
-            #   func() (in module bar)
-            # into
-            #   func()
-            #     (in module foo)
-            #     (in module bar)
-            oldkey = ''
-            oldsubitems = None
-            i = 0
-            while i < len(newlist):
-                key, (targets, subitems) = newlist[i]
-                # cannot move if it has subitems; structure gets too complex
-                if not subitems:
-                    m = _fixre.match(key)
-                    if m:
-                        if oldkey == m.group(1):
-                            # prefixes match: add entry as subitem of the
-                            # previous entry
-                            oldsubitems.setdefault(m.group(2), [[], {}])[0].\
-                                        extend(targets)
-                            del newlist[i]
-                            continue
-                        oldkey = m.group(1)
-                    else:
-                        oldkey = key
-                oldsubitems = subitems
-                i += 1
-
-        # group the entries by letter
-        def keyfunc2(item, letters=string.ascii_uppercase + '_'):
-            # hack: mutating the subitems dicts to a list in the keyfunc
-            k, v = item
-            v[1] = sorted((si, se) for (si, (se, void)) in v[1].iteritems())
-            # now calculate the key
-            letter = unicodedata.normalize('NFD', k[0])[0].upper()
-            if letter in letters:
-                return letter
-            else:
-                # get all other symbols under one heading
-                return 'Symbols'
-        return [(key, list(group))
-                for (key, group) in groupby(newlist, keyfunc2)]
-
-    def collect_relations(self):
-        relations = {}
-        getinc = self.toctree_includes.get
-        def collect(parents, parents_set, docname, previous, next):
-            # circular relationship?
-            if docname in parents_set:
-                # we will warn about this in resolve_toctree()
-                return
-            includes = getinc(docname)
-            # previous
-            if not previous:
-                # if no previous sibling, go to parent
-                previous = parents[0][0]
-            else:
-                # else, go to previous sibling, or if it has children, to
-                # the last of its children, or if that has children, to the
-                # last of those, and so forth
-                while 1:
-                    previncs = getinc(previous)
-                    if previncs:
-                        previous = previncs[-1]
-                    else:
-                        break
-            # next
-            if includes:
-                # if it has children, go to first of them
-                next = includes[0]
-            elif next:
-                # else, if next sibling, go to it
-                pass
-            else:
-                # else, go to the next sibling of the parent, if present,
-                # else the grandparent's sibling, if present, and so forth
-                for parname, parindex in parents:
-                    parincs = getinc(parname)
-                    if parincs and parindex + 1 < len(parincs):
-                        next = parincs[parindex+1]
-                        break
-                # else it will stay None
-            # same for children
-            if includes:
-                for subindex, args in enumerate(izip(includes,
-                                                     [None] + includes,
-                                                     includes[1:] + [None])):
-                    collect([(docname, subindex)] + parents,
-                            parents_set.union([docname]), *args)
-            relations[docname] = [parents[0][0], previous, next]
-        collect([(None, 0)], set(), self.config.master_doc, None, None)
-        return relations
-
-    def check_consistency(self):
-        """Do consistency checks."""
-        for docname in sorted(self.all_docs):
-            if docname not in self.files_to_rebuild:
-                if docname == self.config.master_doc:
-                    # the master file is not included anywhere ;)
-                    continue
-                if 'orphan' in self.metadata[docname]:
-                    continue
-                self.warn(docname, 'document isn\'t included in any toctree')
-

=== added directory '.pc/test_build_html_rb.diff'
=== added directory '.pc/test_build_html_rb.diff/tests'
=== added file '.pc/test_build_html_rb.diff/tests/test_build_html.py'
--- .pc/test_build_html_rb.diff/tests/test_build_html.py	1970-01-01 00:00:00 +0000
+++ .pc/test_build_html_rb.diff/tests/test_build_html.py	2012-11-28 07:12:20 +0000
@@ -0,0 +1,339 @@
+# -*- coding: utf-8 -*-
+"""
+    test_build_html
+    ~~~~~~~~~~~~~~~
+
+    Test the HTML builder and check output against XPath.
+
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import os
+import re
+import sys
+import htmlentitydefs
+from StringIO import StringIO
+
+try:
+    import pygments
+except ImportError:
+    pygments = None
+
+from sphinx import __version__
+from util import *
+from etree13 import ElementTree as ET
+
+
+def teardown_module():
+    (test_root / '_build').rmtree(True)
+
+
+html_warnfile = StringIO()
+
+ENV_WARNINGS = """\
+%(root)s/autodoc_fodder.py:docstring of autodoc_fodder\\.MarkupError:2: \
+WARNING: Explicit markup ends without a blank line; unexpected \
+unindent\\.\\n?
+%(root)s/images.txt:9: WARNING: image file not readable: foo.png
+%(root)s/images.txt:23: WARNING: nonlocal image URI found: \
+http://www.python.org/logo.png
+%(root)s/includes.txt:\\d*: WARNING: Encoding 'utf-8-sig' used for \
+reading included file u'.*?wrongenc.inc' seems to be wrong, try giving an \
+:encoding: option\\n?
+%(root)s/includes.txt:4: WARNING: download file not readable: .*?nonexisting.png
+%(root)s/objects.txt:\\d*: WARNING: using old C markup; please migrate to \
+new-style markup \(e.g. c:function instead of cfunction\), see \
+http://sphinx.pocoo.org/domains.html
+"""
+
+HTML_WARNINGS = ENV_WARNINGS + """\
+%(root)s/images.txt:20: WARNING: no matching candidate for image URI u'foo.\\*'
+%(root)s/markup.txt:: WARNING: invalid single index entry u''
+%(root)s/markup.txt:: WARNING: invalid pair index entry u''
+%(root)s/markup.txt:: WARNING: invalid pair index entry u'keyword; '
+"""
+
+if sys.version_info >= (3, 0):
+    ENV_WARNINGS = remove_unicode_literals(ENV_WARNINGS)
+    HTML_WARNINGS = remove_unicode_literals(HTML_WARNINGS)
+
+
+def tail_check(check):
+    rex = re.compile(check)
+    def checker(nodes):
+        for node in nodes:
+            if node.tail and rex.search(node.tail):
+                return True
+        assert False, '%r not found in tail of any nodes %s' % (check, nodes)
+    return checker
+
+
+HTML_XPATH = {
+    'images.html': [
+        (".//img[@src='_images/img.png']", ''),
+        (".//img[@src='_images/img1.png']", ''),
+        (".//img[@src='_images/simg.png']", ''),
+        (".//img[@src='_images/svgimg.svg']", ''),
+    ],
+    'subdir/images.html': [
+        (".//img[@src='../_images/img1.png']", ''),
+        (".//img[@src='../_images/rimg.png']", ''),
+    ],
+    'subdir/includes.html': [
+        (".//a[@href='../_downloads/img.png']", ''),
+        (".//img[@src='../_images/img.png']", ''),
+        (".//p", 'This is an include file.'),
+    ],
+    'includes.html': [
+        (".//pre", u'Max Strauß'),
+        (".//a[@href='_downloads/img.png']", ''),
+        (".//a[@href='_downloads/img1.png']", ''),
+        (".//pre", u'"quotes"'),
+        (".//pre", u"'included'"),
+    ],
+    'autodoc.html': [
+        (".//dt[@id='test_autodoc.Class']", ''),
+        (".//dt[@id='test_autodoc.function']/em", r'\*\*kwds'),
+        (".//dd/p", r'Return spam\.'),
+    ],
+    'extapi.html': [
+        (".//strong", 'from function: Foo'),
+        (".//strong", 'from class: Bar'),
+    ],
+    'markup.html': [
+        (".//title", 'set by title directive'),
+        (".//p/em", 'Section author: Georg Brandl'),
+        (".//p/em", 'Module author: Georg Brandl'),
+        # created by the meta directive
+        (".//meta[@name='author'][@content='Me']", ''),
+        (".//meta[@name='keywords'][@content='docs, sphinx']", ''),
+        # a label created by ``.. _label:``
+        (".//div[@id='label']", ''),
+        # code with standard code blocks
+        (".//pre", '^some code$'),
+        # an option list
+        (".//span[@class='option']", '--help'),
+        # admonitions
+        (".//p[@class='first admonition-title']", 'My Admonition'),
+        (".//p[@class='last']", 'Note text.'),
+        (".//p[@class='last']", 'Warning text.'),
+        # inline markup
+        (".//li/strong", r'^command\\n$'),
+        (".//li/strong", r'^program\\n$'),
+        (".//li/em", r'^dfn\\n$'),
+        (".//li/tt/span[@class='pre']", r'^kbd\\n$'),
+        (".//li/em", u'File \N{TRIANGULAR BULLET} Close'),
+        (".//li/tt/span[@class='pre']", '^a/$'),
+        (".//li/tt/em/span[@class='pre']", '^varpart$'),
+        (".//li/tt/em/span[@class='pre']", '^i$'),
+        (".//a[@href='http://www.python.org/dev/peps/pep-0008']"
+            "[@class='pep reference external']/strong", 'PEP 8'),
+        (".//a[@href='http://tools.ietf.org/html/rfc1.html']"
+            "[@class='rfc reference external']/strong", 'RFC 1'),
+        (".//a[@href='objects.html#envvar-HOME']"
+            "[@class='reference internal']/tt/span[@class='pre']", 'HOME'),
+        (".//a[@href='#with']"
+            "[@class='reference internal']/tt/span[@class='pre']", '^with$'),
+        (".//a[@href='#grammar-token-try_stmt']"
+            "[@class='reference internal']/tt/span", '^statement$'),
+        (".//a[@href='subdir/includes.html']"
+            "[@class='reference internal']/em", 'Including in subdir'),
+        (".//a[@href='objects.html#cmdoption-python-c']"
+            "[@class='reference internal']/em", 'Python -c option'),
+        # abbreviations
+        (".//abbr[@title='abbreviation']", '^abbr$'),
+        # version stuff
+        (".//span[@class='versionmodified']", 'New in version 0.6'),
+        # footnote reference
+        (".//a[@class='footnote-reference']", r'\[1\]'),
+        # created by reference lookup
+        (".//a[@href='contents.html#ref1']", ''),
+        # ``seealso`` directive
+        (".//div/p[@class='first admonition-title']", 'See also'),
+        # a ``hlist`` directive
+        (".//table[@class='hlist']/tr/td/ul/li", '^This$'),
+        # a ``centered`` directive
+        (".//p[@class='centered']/strong", 'LICENSE'),
+        # a glossary
+        (".//dl/dt[@id='term-boson']", 'boson'),
+        # a production list
+        (".//pre/strong", 'try_stmt'),
+        (".//pre/a[@href='#grammar-token-try1_stmt']/tt/span", 'try1_stmt'),
+        # tests for ``only`` directive
+        (".//p", 'A global substitution.'),
+        (".//p", 'In HTML.'),
+        (".//p", 'In both.'),
+        (".//p", 'Always present'),
+    ],
+    'objects.html': [
+        (".//dt[@id='mod.Cls.meth1']", ''),
+        (".//dt[@id='errmod.Error']", ''),
+        (".//dt/tt", r'long\(parameter,\s* list\)'),
+        (".//dt/tt", 'another one'),
+        (".//a[@href='#mod.Cls'][@class='reference internal']", ''),
+        (".//dl[@class='userdesc']", ''),
+        (".//dt[@id='userdesc-myobj']", ''),
+        (".//a[@href='#userdesc-myobj'][@class='reference internal']", ''),
+        # C references
+        (".//span[@class='pre']", 'CFunction()'),
+        (".//a[@href='#Sphinx_DoSomething']", ''),
+        (".//a[@href='#SphinxStruct.member']", ''),
+        (".//a[@href='#SPHINX_USE_PYTHON']", ''),
+        (".//a[@href='#SphinxType']", ''),
+        (".//a[@href='#sphinx_global']", ''),
+        # reference from old C markup extension
+        (".//a[@href='#Sphinx_Func']", ''),
+        # test global TOC created by toctree()
+        (".//ul[@class='current']/li[@class='toctree-l1 current']/a[@href='']",
+            'Testing object descriptions'),
+        (".//li[@class='toctree-l1']/a[@href='markup.html']",
+            'Testing various markup'),
+        # custom sidebar
+        (".//h4", 'Custom sidebar'),
+        # docfields
+        (".//td[@class='field-body']/strong", '^moo$'),
+        (".//td[@class='field-body']/strong",
+             tail_check(r'\(Moo\) .* Moo')),
+        (".//td[@class='field-body']/ul/li/strong", '^hour$'),
+        (".//td[@class='field-body']/ul/li/em", '^DuplicateType$'),
+        (".//td[@class='field-body']/ul/li/em",
+             tail_check(r'.* Some parameter')),
+    ],
+    'contents.html': [
+        (".//meta[@name='hc'][@content='hcval']", ''),
+        (".//meta[@name='hc_co'][@content='hcval_co']", ''),
+        (".//meta[@name='testopt'][@content='testoverride']", ''),
+        (".//td[@class='label']", r'\[Ref1\]'),
+        (".//td[@class='label']", ''),
+        (".//li[@class='toctree-l1']/a", 'Testing various markup'),
+        (".//li[@class='toctree-l2']/a", 'Inline markup'),
+        (".//title", 'Sphinx <Tests>'),
+        (".//div[@class='footer']", 'Georg Brandl & Team'),
+        (".//a[@href='http://python.org/']"
+            "[@class='reference external']", ''),
+        (".//li/a[@href='genindex.html']/em", 'Index'),
+        (".//li/a[@href='py-modindex.html']/em", 'Module Index'),
+        (".//li/a[@href='search.html']/em", 'Search Page'),
+        # custom sidebar only for contents
+        (".//h4", 'Contents sidebar'),
+        # custom JavaScript
+        (".//script[@src='file://moo.js']", ''),
+    ],
+    'bom.html': [
+        (".//title", " File with UTF-8 BOM"),
+    ],
+    'extensions.html': [
+        (".//a[@href='http://python.org/dev/']", "http://python.org/dev/"),
+        (".//a[@href='http://bugs.python.org/issue1000']", "issue 1000"),
+        (".//a[@href='http://bugs.python.org/issue1042']", "explicit caption"),
+    ],
+    '_static/statictmpl.html': [
+        (".//project", 'Sphinx <Tests>'),
+    ],
+    'genindex.html': [
+        # index entries
+        (".//a/strong", "Main"),
+        (".//a/strong", "[1]"),
+        (".//a/strong", "Other"),
+        (".//a", "entry"),
+        (".//dt/a", "double"),
+    ]
+}
+
+if pygments:
+    HTML_XPATH['includes.html'].extend([
+        (".//pre/span[@class='s']", u'üöä'),
+        (".//div[@class='inc-pyobj1 highlight-text']//pre",
+            r'^class Foo:\n    pass\n\s*$'),
+        (".//div[@class='inc-pyobj2 highlight-text']//pre",
+            r'^    def baz\(\):\n        pass\n\s*$'),
+        (".//div[@class='inc-lines highlight-text']//pre",
+            r'^class Foo:\n    pass\nclass Bar:\n$'),
+        (".//div[@class='inc-startend highlight-text']//pre",
+            ur'^foo = "Including Unicode characters: üöä"\n$'),
+        (".//div[@class='inc-preappend highlight-text']//pre",
+            r'(?m)^START CODE$'),
+        (".//div[@class='inc-pyobj-dedent highlight-python']//span",
+            r'def'),
+        (".//div[@class='inc-tab3 highlight-text']//pre",
+            r'-| |-'),
+        (".//div[@class='inc-tab8 highlight-python']//pre/span",
+            r'-|      |-'),
+    ])
+    HTML_XPATH['subdir/includes.html'].extend([
+        (".//pre/span", 'line 1'),
+        (".//pre/span", 'line 2'),
+    ])
+
+class NslessParser(ET.XMLParser):
+    """XMLParser that throws away namespaces in tag names."""
+
+    def _fixname(self, key):
+        try:
+            return self._names[key]
+        except KeyError:
+            name = key
+            br = name.find('}')
+            if br > 0:
+                name = name[br+1:]
+            self._names[key] = name = self._fixtext(name)
+            return name
+
+
+def check_xpath(etree, fname, path, check):
+    nodes = list(etree.findall(path))
+    assert nodes != [], ('did not find any node matching xpath '
+                         '%r in file %s' % (path, fname))
+    if hasattr(check, '__call__'):
+        check(nodes)
+    elif not check:
+        # only check for node presence
+        pass
+    else:
+        rex = re.compile(check)
+        for node in nodes:
+            if node.text and rex.search(node.text):
+                break
+        else:
+            assert False, ('%r not found in any node matching '
+                           'path %s in %s: %r' % (check, path, fname,
+                           [node.text for node in nodes]))
+
+def check_static_entries(outdir):
+    staticdir = outdir / '_static'
+    assert staticdir.isdir()
+    # a file from a directory entry in html_static_path
+    assert (staticdir / 'README').isfile()
+    # a directory from a directory entry in html_static_path
+    assert (staticdir / 'subdir' / 'foo.css').isfile()
+    # a file from a file entry in html_static_path
+    assert (staticdir / 'templated.css').isfile()
+    assert (staticdir / 'templated.css').text().splitlines()[1] == __version__
+    # a file from _static, but matches exclude_patterns
+    assert not (staticdir / 'excluded.css').exists()
+
+@gen_with_app(buildername='html', warning=html_warnfile, cleanenv=True,
+              confoverrides={'html_context.hckey_co': 'hcval_co'},
+              tags=['testtag'])
+def test_html(app):
+    app.builder.build_all()
+    html_warnings = html_warnfile.getvalue().replace(os.sep, '/')
+    html_warnings_exp = HTML_WARNINGS % {'root': re.escape(app.srcdir)}
+    assert re.match(html_warnings_exp + '$', html_warnings), \
+           'Warnings don\'t match:\n' + \
+           '--- Expected (regex):\n' + html_warnings_exp + \
+           '--- Got:\n' + html_warnings
+
+    for fname, paths in HTML_XPATH.iteritems():
+        parser = NslessParser()
+        parser.entity.update(htmlentitydefs.entitydefs)
+        fp = open(os.path.join(app.outdir, fname))
+        try:
+            etree = ET.parse(fp, parser)
+        finally:
+            fp.close()
+        for path, check in paths:
+            yield check_xpath, etree, fname, path, check
+
+    check_static_entries(app.builder.outdir)

=== modified file 'debian/changelog'
--- debian/changelog	2012-11-01 21:39:16 +0000
+++ debian/changelog	2012-11-28 07:12:20 +0000
@@ -1,3 +1,61 @@
+sphinx (1.1.3+dfsg-5ubuntu1) UNRELEASED; urgency=low
+
+  * Merge with Debian packaging SVN.
+    - This brings in fix for LP: #1068493.
+  * Remaining Ubuntu changes:
+    - Switch to dh_python2.
+    - debian/rules: export NO_PKG_MANGLE=1 in order to not have translations
+      stripped.
+    - debian/rules: Modify xvfb-run to use auto-servernum flag (fixes FTBFS).
+    - debian/control: Drop the dependency on python-whoosh.
+    - debian/control: Add "XS-Testsuite: autopkgtest" header.
+    - debian/patches/fix_manpages_generation_with_new_docutils.diff:
+      Fix FTBFS with the new python-docutils package.
+
+ -- Dmitry Shachnev <[e-mail]>  Tue, 27 Nov 2012 19:20:44 +0400
+
+sphinx (1.1.3+dfsg-6) UNRELEASED; urgency=low
+
+  [ Jakub Wilk ]
+  * DEP-8 tests: remove “Features: no-build-needed”; it's the default now.
+  * Bump standards version to 3.9.4; no changes needed.
+
+  [ Dmitry Shachnev ]
+  * debian/patches/l10n_fixes.diff: fix crashes and not working external
+    links in l10n mode (closes: #691719).
+
+ -- Jakub Wilk <[e-mail]>  Tue, 13 Nov 2012 22:36:10 +0100
+
+sphinx (1.1.3+dfsg-5) experimental; urgency=low
+
+  [ Jakub Wilk ]
+  * DEP-8 tests: use $ADTTMP.
+  * dh_sphinxdoc: ignore comments when analysing HTML files (closes: #682850).
+    Thanks to Dmitry Shachnev for the bug report.
+  * Add dvipng to Suggests (closes: #687273). Thanks to Matthias Klose for the
+    bug report.
+  * Set PYTHONHASHSEED=random in debian/rules and in DEP-8 tests.
+  * Backport upstream patch to fix encoding issues in test_build_html. Now
+    that this is fixed, stop running Python 3 tests under LC_ALL=C.
+  * Make “debian/rules binary-arch” no-op.
+  * Update version number in the sphinx-autogen manpage.
+  * Improve dh_sphinxdoc:
+    + Fix the --tmpdir option. Thanks to Andriy Senkovych for the bug report.
+    + Ignore references to JavaScript code that start with an URI scheme.
+      Thanks to Dmitry Shachnev for the bug report.
+    + Strip query (?...) and fragment (#...) components from JavaScript
+      references. Thanks to Dmitry Shachnev for the bug report.
+  * Sort stopwords in searchtools.js. Thanks to Dmitry Shachnev for the bug
+    report.
+  * Fix compatibility with Python 3.3. Thanks to Dmitry Shachnev for the bug
+    report and hunting down the upstream patch.
+
+  [ Dmitry Shachnev ]
+  * Update Homepage field to point to http://sphinx-doc.org/.
+  * Build-depend of python3-all instead of python3.
+
+ -- Jakub Wilk <[e-mail]>  Thu, 08 Nov 2012 16:28:23 +0100
+
 sphinx (1.1.3+dfsg-4ubuntu5) raring; urgency=low
 
   * Build-depend on python3-all instead of python3.

=== modified file 'debian/control'
--- debian/control	2012-11-01 21:39:16 +0000
+++ debian/control	2012-11-28 07:12:20 +0000
@@ -22,7 +22,7 @@
 XS-Python-Version: >= 2.5
 X-Python3-Version: >= 3.1
 XS-Testsuite: autopkgtest
-Standards-Version: 3.9.3
+Standards-Version: 3.9.4
 Vcs-Svn: svn://svn.debian.org/python-modules/packages/sphinx/trunk/
 Vcs-Browser: http://svn.debian.org/viewsvn/python-modules/packages/sphinx/trunk/
 
@@ -36,7 +36,7 @@
 Recommends: python (>= 2.6) | python-simplejson, python-imaging,
   sphinx-doc
 Suggests:
-  jsmath, libjs-mathjax,
+  jsmath, libjs-mathjax, dvipng,
   texlive-latex-recommended, texlive-latex-extra, texlive-fonts-recommended
 Description: documentation generator for Python projects (implemented in Python 2)
  Sphinx is a tool for producing documentation for Python projects, using
@@ -62,7 +62,7 @@
   sphinx-common (= ${source:Version})
 Recommends: python3-imaging
 Suggests:
-  jsmath, libjs-mathjax,
+  jsmath, libjs-mathjax, dvipng,
   texlive-latex-recommended, texlive-latex-extra, texlive-fonts-recommended,
   sphinx-doc
 Description: documentation generator for Python projects (implemented in Python 3)

=== modified file 'debian/dh-sphinxdoc/dh_sphinxdoc'
--- debian/dh-sphinxdoc/dh_sphinxdoc	2012-08-21 17:45:58 +0000
+++ debian/dh-sphinxdoc/dh_sphinxdoc	2012-11-28 07:12:20 +0000
@@ -109,7 +109,9 @@
 sub load_packaged_js()
 {
     my %versions = ();
-    my $root = tmpdir('libjs-sphinxdoc');    
+    my $root = 'debian/libjs-sphinxdoc'; # It's tempting to use
+    # tmpdir('libjs-sphinxdoc') here, but it would break if the user passed
+    # --tmpdir to the command.
     $root = '' unless -d $root;
     my $path = "$root/usr/share/javascript/sphinxdoc";
     open(F, '<', "$path/index") or error("cannot open $path/index");
@@ -185,7 +187,7 @@
     close F;
     $search =~ s/<!--.*?-->//g; # strip comments
     my %js = ();
-    grep { $js{$_} = 1 unless excludefile("$path/$_"); } $search =~ m{<script type="text/javascript" src="([^"]++)"></script>}g;
+    grep { s/[?#].*//; $js{$_} = 1 unless m/^[a-z][a-z0-9.+-]*:/i or excludefile("$path/$_"); } $search =~ m{<script type="text/javascript" src="([^"]++)"></script>}g;
     my $loads_searchindex = $search =~ m/\QjQuery(function() { Search.loadIndex("searchindex.js"); });\E/;
     my ($has_source) = $search =~ m{HAS_SOURCE:\s*(true|false)};
     my ($url_root) = $search =~ m{URL_ROOT:\s*'([^']*)'};

=== added file 'debian/patches/l10n_fixes.diff'
--- debian/patches/l10n_fixes.diff	1970-01-01 00:00:00 +0000
+++ debian/patches/l10n_fixes.diff	2012-11-28 07:12:20 +0000
@@ -0,0 +1,58 @@
+Description: Fix l10n build of text containing footnotes
+ Based on initial patch by Cristophe Simonis and modifications by Takayuki Shimizukawa
+ (upstream pull request #86).
+Bug: https://bitbucket.org/birkenfeld/sphinx/issue/955/cant-build-html-with-footnotes-when-using
+Bug-Debian: http://bugs.debian.org/691719
+Author: Takayuki Shimizukawa <[e-mail]>
+Last-Update: 2012-11-27
+
+=== modified file 'sphinx/environment.py'
+--- a/sphinx/environment.py	2012-03-12 12:18:37 +0000
++++ b/sphinx/environment.py	2012-11-27 14:05:36 +0000
+@@ -213,16 +213,44 @@
+         parser = RSTParser()
+ 
+         for node, msg in extract_messages(self.document):
+-            patch = new_document(source, settings)
+             msgstr = catalog.gettext(msg)
+             # XXX add marker to untranslated parts
+             if not msgstr or msgstr == msg: # as-of-yet untranslated
+                 continue
++
++            patch = new_document(source, settings)
+             parser.parse(msgstr, patch)
+             patch = patch[0]
+             # XXX doctest and other block markup
+             if not isinstance(patch, nodes.paragraph):
+                 continue # skip for now
++
++            footnote_refs = [r for r in node.children
++                             if isinstance(r, nodes.footnote_reference)
++                             and r.get('auto') == 1]
++            refs = [r for r in node.children if isinstance(r, nodes.reference)]
++
++            for i, child in enumerate(patch.children): # update leaves
++                if isinstance(child, nodes.footnote_reference) \
++                   and child.get('auto') == 1:
++                    # use original 'footnote_reference' object.
++                    # this object is already registered in self.document.autofootnote_refs
++                    patch.children[i] = footnote_refs.pop(0)
++                    # Some duplicated footnote_reference in msgstr causes
++                    # IndexError in .pop(0). That is invalid msgstr.
++
++                elif isinstance(child, nodes.reference):
++                    # reference should use original 'refname'.
++                    # * reference target ".. _Python: ..." is not translatable.
++                    # * section refname is not translatable.
++                    # * inline reference "`Python <...>`_" has no 'refname'.
++                    if refs and 'refname' in refs[0]:
++                        refname = child['refname'] = refs.pop(0)['refname']
++                        self.document.refnames.setdefault(
++                                refname, []).append(child)
++                    # if number of reference nodes had been changed, that
++                    # would often generate unknown link target warning.
++
+             for child in patch.children: # update leaves
+                 child.parent = node
+             node.children = patch.children
+

=== modified file 'debian/patches/series'
--- debian/patches/series	2012-11-01 21:39:16 +0000
+++ debian/patches/series	2012-11-28 07:12:20 +0000
@@ -9,4 +9,7 @@
 pygments_byte_strings.diff
 fix_shorthandoff.diff
 fix_manpages_generation_with_new_docutils.diff
+test_build_html_rb.diff
+sort_stopwords.diff
 support_python_3.3.diff
+l10n_fixes.diff

=== added file 'debian/patches/sort_stopwords.diff'
--- debian/patches/sort_stopwords.diff	1970-01-01 00:00:00 +0000
+++ debian/patches/sort_stopwords.diff	2012-11-28 07:12:20 +0000
@@ -0,0 +1,16 @@
+Description: sort stopwords in searchtools.js
+ The order of stopwords in searchtools.js would be random if hash randomization
+ was enabled, breaking dh_sphinxdoc. This patch makes the order deterministic.
+Author: Jakub Wilk <[e-mail]>
+Applied-Upstream: https://bitbucket.org/birkenfeld/sphinx/changeset/6cf5320e65
+Last-Update: 2012-11-10
+
+--- a/sphinx/search/__init__.py
++++ b/sphinx/search/__init__.py
+@@ -283,5 +283,5 @@
+     def context_for_searchtool(self):
+         return dict(
+             search_language_stemming_code = self.lang.js_stemmer_code,
+-            search_language_stop_words = jsdump.dumps(self.lang.stopwords),
++            search_language_stop_words = jsdump.dumps(sorted(self.lang.stopwords)),
+         )

=== modified file 'debian/patches/support_python_3.3.diff'
--- debian/patches/support_python_3.3.diff	2012-11-01 21:39:16 +0000
+++ debian/patches/support_python_3.3.diff	2012-11-28 07:12:20 +0000
@@ -1,29 +1,11 @@
-Description: Fix various testsuite failures with Python 3.3
+Description: fix compatibility with Python 3.3
 Author: Takayuki Shimizukawa <[e-mail]>
 Bug: https://bitbucket.org/birkenfeld/sphinx/issue/1008/test-failures-with-python-33
 Bug-Ubuntu: https://bugs.launchpad.net/bugs/1070336
-Last-Update: 2012-11-01
-
-=== modified file 'sphinx/environment.py'
---- a/sphinx/environment.py	2012-03-30 23:32:16 +0000
-+++ b/sphinx/environment.py	2012-11-01 17:33:08 +0000
-@@ -782,7 +782,11 @@
-             app.emit('doctree-read', doctree)
- 
-         # store time of build, for outdated files detection
--        self.all_docs[docname] = time.time()
-+        # (Some filesystems have coarse timestamp resolution;
-+        # therefore time.time() is older than filesystem's timestamp.
-+        # For example, FAT32 has 2sec timestamp resolution.)
-+        self.all_docs[docname] = max(
-+                time.time(), path.getmtime(self.doc2path(docname)))
- 
-         if self.versioning_condition:
-             # get old doctree
-
-=== modified file 'sphinx/ext/autodoc.py'
---- a/sphinx/ext/autodoc.py	2012-03-30 23:32:16 +0000
-+++ b/sphinx/ext/autodoc.py	2012-11-01 17:33:08 +0000
+Last-Update: 2012-11-08
+
+--- a/sphinx/ext/autodoc.py
++++ b/sphinx/ext/autodoc.py
 @@ -1098,7 +1098,7 @@
      """
      objtype = 'method'
@@ -33,10 +15,8 @@
  
      @classmethod
      def can_document_member(cls, member, membername, isattr, parent):
-
-=== modified file 'sphinx/ext/intersphinx.py'
---- a/sphinx/ext/intersphinx.py	2012-03-30 23:32:16 +0000
-+++ b/sphinx/ext/intersphinx.py	2012-11-01 17:33:13 +0000
+--- a/sphinx/ext/intersphinx.py
++++ b/sphinx/ext/intersphinx.py
 @@ -188,7 +188,17 @@
      if update:
          env.intersphinx_inventory = {}
@@ -56,17 +36,13 @@
              if name:
                  env.intersphinx_named_inventory[name] = invdata
              for type, objects in invdata.iteritems():
-
-=== modified file 'sphinx/util/__init__.py'
---- a/sphinx/util/__init__.py	2012-03-30 23:32:16 +0000
-+++ b/sphinx/util/__init__.py	2012-11-01 17:37:41 +0000
+--- a/sphinx/util/__init__.py
++++ b/sphinx/util/__init__.py
 @@ -197,13 +197,18 @@
          except Exception, err:
              raise PycodeError('error importing %r' % modname, err)
      mod = sys.modules[modname]
 -    if hasattr(mod, '__loader__'):
--        try:
--            source = mod.__loader__.get_source(modname)
 +    filename = getattr(mod, '__file__', None)
 +    loader = getattr(mod, '__loader__', None)
 +    if loader and getattr(loader, 'get_filename', None):
@@ -75,7 +51,8 @@
 +        except Exception, err:
 +            raise PycodeError('error getting filename for %r' % filename, err)
 +    if filename is None and loader:
-+        try:
+         try:
+-            source = mod.__loader__.get_source(modname)
 +            return 'string', loader.get_source(modname)
          except Exception, err:
              raise PycodeError('error getting source for %r' % modname, err)
@@ -84,4 +61,3 @@
      if filename is None:
          raise PycodeError('no source found for module %r' % modname)
      filename = path.normpath(path.abspath(filename))
-

=== added file 'debian/patches/test_build_html_rb.diff'
--- debian/patches/test_build_html_rb.diff	1970-01-01 00:00:00 +0000
+++ debian/patches/test_build_html_rb.diff	2012-11-28 07:12:20 +0000
@@ -0,0 +1,17 @@
+Description: fix encoding issues in test_build_html
+ test_build_html: open files that are fed to ElementTree parser in "rb"
+ mode, fixing encoding issues.
+Origin: upstream, https://bitbucket.org/birkenfeld/sphinx/changeset/15c9d212bbf4
+Bug: https://bitbucket.org/birkenfeld/sphinx/issue/895
+
+--- a/tests/test_build_html.py
++++ b/tests/test_build_html.py
+@@ -328,7 +328,7 @@
+     for fname, paths in HTML_XPATH.iteritems():
+         parser = NslessParser()
+         parser.entity.update(htmlentitydefs.entitydefs)
+-        fp = open(os.path.join(app.outdir, fname))
++        fp = open(os.path.join(app.outdir, fname), 'rb')
+         try:
+             etree = ET.parse(fp, parser)
+         finally:

=== modified file 'debian/rules'
--- debian/rules	2012-06-19 09:06:35 +0000
+++ debian/rules	2012-11-28 07:12:20 +0000
@@ -5,6 +5,7 @@
 
 export NO_PKG_MANGLE=1
 export PYTHONWARNINGS=d
+export PYTHONHASHSEED=random
 
 here = $(dir $(firstword $(MAKEFILE_LIST)))/..
 debian_version = $(word 2,$(shell cd $(here) && dpkg-parsechangelog | grep ^Version:))
@@ -39,7 +40,7 @@
 ifeq (,$(filter nocheck,$(DEB_BUILD_OPTIONS)))
 	find sphinx/locale/ -name '*.po' | xargs -t -I {} msgfmt -o /dev/null -c {}
 	$(python_all) tests/run.py --verbose --no-skip
-	export LC_ALL=C.UTF-8 && $(python3_all) tests/run.py --verbose
+	$(python3_all) tests/run.py --verbose
 	cd build/py3/ && rm -rf tests/ sphinx/pycode/Grammar.pickle
 	xvfb-run --auto-servernum ./debian/jstest/run-tests
 endif
@@ -146,7 +147,7 @@
 	dh_md5sums
 	dh_builddeb
 
-binary-arch: build install
+binary-arch:
 
 binary: binary-indep binary-arch
 

=== modified file 'debian/sphinx-autogen.1'
--- debian/sphinx-autogen.1	2011-11-20 15:56:50 +0000
+++ debian/sphinx-autogen.1	2012-11-28 07:12:20 +0000
@@ -1,4 +1,4 @@
-.TH sphinx\-autogen 1 "Aug 2010" "Sphinx 1.1" "User Commands"
+.TH sphinx\-autogen 1 "Nov 2012" "Sphinx 1.1.3" "User Commands"
 
 .SH NAME
 sphinx\-autogen \- generate ReStructuredText using \fBautosummary\fR

=== modified file 'debian/tests/control'
--- debian/tests/control	2012-05-24 18:53:29 +0000
+++ debian/tests/control	2012-11-28 07:12:20 +0000
@@ -1,7 +1,5 @@
 Tests: python-sphinx
-Features: no-build-needed
 Depends: python-sphinx, python-nose
 
 Tests: python3-sphinx
-Features: no-build-needed
 Depends: python3-sphinx, python3-nose

=== modified file 'debian/tests/python-sphinx'
--- debian/tests/python-sphinx	2012-08-21 17:45:58 +0000
+++ debian/tests/python-sphinx	2012-11-28 07:12:20 +0000
@@ -4,7 +4,7 @@
 cd "$ADTTMP"
 pyversions -i \
 | tr ' ' '\n' \
-| xargs -I {} env PYTHONWARNINGS=d {} \
+| xargs -I {} env PYTHONWARNINGS=d PYTHONHASHSEED=random {} \
   /usr/bin/nosetests --verbose 2>&1
 
 # vim:ts=4 sw=4 et

=== modified file 'debian/tests/python3-sphinx'
--- debian/tests/python3-sphinx	2012-08-21 17:45:58 +0000
+++ debian/tests/python3-sphinx	2012-11-28 07:12:20 +0000
@@ -5,7 +5,7 @@
 cd "$ADTTMP"
 py3versions -i \
 | tr ' ' '\n' \
-| xargs -I {} env PYTHONWARNINGS=d {} \
+| xargs -I {} env PYTHONWARNINGS=d PYTHONHASHSEED=random {} \
   /usr/bin/nosetests3 --verbose 2>&1
 
 # vim:ts=4 sw=4 et

=== modified file 'sphinx/environment.py'
--- sphinx/environment.py	2012-11-01 21:39:16 +0000
+++ sphinx/environment.py	2012-11-28 07:12:20 +0000
@@ -213,16 +213,44 @@
         parser = RSTParser()
 
         for node, msg in extract_messages(self.document):
-            patch = new_document(source, settings)
             msgstr = catalog.gettext(msg)
             # XXX add marker to untranslated parts
             if not msgstr or msgstr == msg: # as-of-yet untranslated
                 continue
+
+            patch = new_document(source, settings)
             parser.parse(msgstr, patch)
             patch = patch[0]
             # XXX doctest and other block markup
             if not isinstance(patch, nodes.paragraph):
                 continue # skip for now
+
+            footnote_refs = [r for r in node.children
+                             if isinstance(r, nodes.footnote_reference)
+                             and r.get('auto') == 1]
+            refs = [r for r in node.children if isinstance(r, nodes.reference)]
+
+            for i, child in enumerate(patch.children): # update leaves
+                if isinstance(child, nodes.footnote_reference) \
+                   and child.get('auto') == 1:
+                    # use original 'footnote_reference' object.
+                    # this object is already registered in self.document.autofootnote_refs
+                    patch.children[i] = footnote_refs.pop(0)
+                    # Some duplicated footnote_reference in msgstr causes
+                    # IndexError in .pop(0). That is invalid msgstr.
+
+                elif isinstance(child, nodes.reference):
+                    # reference should use original 'refname'.
+                    # * reference target ".. _Python: ..." is not translatable.
+                    # * section refname is not translatable.
+                    # * inline reference "`Python <...>`_" has no 'refname'.
+                    if refs and 'refname' in refs[0]:
+                        refname = child['refname'] = refs.pop(0)['refname']
+                        self.document.refnames.setdefault(
+                                refname, []).append(child)
+                    # if number of reference nodes had been changed, that
+                    # would often generate unknown link target warning.
+
             for child in patch.children: # update leaves
                 child.parent = node
             node.children = patch.children
@@ -782,11 +810,7 @@
             app.emit('doctree-read', doctree)
 
         # store time of build, for outdated files detection
-        # (Some filesystems have coarse timestamp resolution;