Merge branch 'stable'

35 files changed, 223 insertions, 30 deletions

diff --git a/CHANGES b/CHANGES
index 3cdd47ba5..dc7a6e2ef 100644
--- a/CHANGES
+++ b/CHANGES
@@ -12,8 +12,17 @@ Features added
 Bugs fixed
 ----------
 
-Release 1.5.1 (in development)
-==============================
+Release 1.5.2 (in development)
+===============================
+
+Features added
+--------------
+
+Bugs fixed
+----------
+
+Release 1.5.1 (released Dec 13, 2016)
+=====================================
 
 Features added
 --------------
@@ -35,6 +44,9 @@ Bugs fixed
 * #3220: KeyError when having a duplicate citation
 * #3200: LaTeX: xref inside desc_name not allowed
 * #3228: ``build_sphinx`` command crashes when missing dependency
+* #2469: Ignore updates of catalog files for gettext builder. Thanks to
+  Hiroshi Ohkubo.
+* #3183: Randomized jump box order in generated index page.
 
 Release 1.5 (released Dec 5, 2016)
 ==================================
diff --git a/Makefile b/Makefile
index 86226f3b5..0c0fdd40d 100644
--- a/Makefile
+++ b/Makefile
@@ -38,7 +38,7 @@ style-check:
 type-check:
 	mypy sphinx/
 
-clean: clean-pyc clean-pycache clean-patchfiles clean-backupfiles clean-generated clean-testfiles clean-buildfiles
+clean: clean-pyc clean-pycache clean-patchfiles clean-backupfiles clean-generated clean-testfiles clean-buildfiles clean-mypyfiles
 
 clean-pyc:
 	find . -name '*.pyc' -exec rm -f {} +
@@ -65,6 +65,9 @@ clean-testfiles:
 clean-buildfiles:
 	rm -rf build
 
+clean-mypyfiles:
+	rm -rf .mypy_cache/
+
 pylint:
 	@pylint --rcfile utils/pylintrc sphinx
 
diff --git a/sphinx/application.py b/sphinx/application.py
index 8ef373067..398a4a124 100644
--- a/sphinx/application.py
+++ b/sphinx/application.py
@@ -295,7 +295,7 @@ class Sphinx(object):
         if freshenv:
             self.env = BuildEnvironment(self.srcdir, self.doctreedir, self.config)
             self.env.set_warnfunc(self.warn)
-            self.env.find_files(self.config)
+            self.env.find_files(self.config, self.buildername)
             for domain in self.domains.keys():
                 self.env.domains[domain] = self.domains[domain](self.env)
         else:
@@ -559,12 +559,6 @@ class Sphinx(object):
             # special-case for compatibility
             if extension == 'rst2pdf.pdfbuilder':
                 ext_meta = {'parallel_read_safe': True}
-            elif extension in builtin_extensions:
-                ext_meta = {
-                    'version': 'builtin',
-                    'parallel_read_safe': True,
-                    'parallel_write_safe': True,
-                }
         try:
             if not ext_meta.get('version'):
                 ext_meta['version'] = 'unknown version'
diff --git a/sphinx/builders/applehelp.py b/sphinx/builders/applehelp.py
index 05a5a2977..66ee82ff8 100644
--- a/sphinx/builders/applehelp.py
+++ b/sphinx/builders/applehelp.py
@@ -301,3 +301,9 @@ def setup(app):
     app.add_config_value('applehelp_indexer_path', '/usr/bin/hiutil', 'applehelp')
     app.add_config_value('applehelp_codesign_path', '/usr/bin/codesign', 'applehelp')
     app.add_config_value('applehelp_disable_external_tools', False, None)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/builders/changes.py b/sphinx/builders/changes.py
index 034722929..708cefcde 100644
--- a/sphinx/builders/changes.py
+++ b/sphinx/builders/changes.py
@@ -167,3 +167,9 @@ class ChangesBuilder(Builder):
 def setup(app):
     # type: (Sphinx) -> None
     app.add_builder(ChangesBuilder)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/builders/devhelp.py b/sphinx/builders/devhelp.py
index f0b313e7f..e615de39b 100644
--- a/sphinx/builders/devhelp.py
+++ b/sphinx/builders/devhelp.py
@@ -137,3 +137,9 @@ def setup(app):
     app.add_builder(DevhelpBuilder)
 
     app.add_config_value('devhelp_basename', lambda self: make_filename(self.project), None)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/builders/dummy.py b/sphinx/builders/dummy.py
index b119d9687..2fb146ecf 100644
--- a/sphinx/builders/dummy.py
+++ b/sphinx/builders/dummy.py
@@ -38,3 +38,9 @@ class DummyBuilder(Builder):
 
 def setup(app):
     app.add_builder(DummyBuilder)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py
index 938a5cc34..d119c62db 100644
--- a/sphinx/builders/epub.py
+++ b/sphinx/builders/epub.py
@@ -866,3 +866,9 @@ def setup(app):
     app.add_config_value('epub_max_image_width', 0, 'env')
     app.add_config_value('epub_show_urls', 'inline', 'html')
     app.add_config_value('epub_use_index', lambda self: self.html_use_index, 'html')
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/builders/epub3.py b/sphinx/builders/epub3.py
index ae799986e..5e0663a08 100644
--- a/sphinx/builders/epub3.py
+++ b/sphinx/builders/epub3.py
@@ -281,3 +281,9 @@ def setup(app):
     app.add_config_value('epub3_description', None, 'epub3', string_classes)
     app.add_config_value('epub3_contributor', None, 'epub3', string_classes)
     app.add_config_value('epub3_page_progression_direction', None, 'epub3', string_classes)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/builders/gettext.py b/sphinx/builders/gettext.py
index dbe696a0b..ecf8cb1f3 100644
--- a/sphinx/builders/gettext.py
+++ b/sphinx/builders/gettext.py
@@ -285,3 +285,9 @@ def setup(app):
     app.add_config_value('gettext_uuid', False, 'gettext')
     app.add_config_value('gettext_auto_build', True, 'env')
     app.add_config_value('gettext_additional_targets', [], 'env')
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py
index b5d68c843..5e1608132 100644
--- a/sphinx/builders/html.py
+++ b/sphinx/builders/html.py
@@ -1323,3 +1323,9 @@ def setup(app):
     app.add_config_value('html_search_options', {}, 'html')
     app.add_config_value('html_search_scorer', '', None)
     app.add_config_value('html_scaled_image_link', True, 'html')
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/builders/htmlhelp.py b/sphinx/builders/htmlhelp.py
index ecc752b60..79268ab74 100644
--- a/sphinx/builders/htmlhelp.py
+++ b/sphinx/builders/htmlhelp.py
@@ -312,3 +312,9 @@ def setup(app):
     app.add_builder(HTMLHelpBuilder)
 
     app.add_config_value('htmlhelp_basename', lambda self: make_filename(self.project), None)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/builders/latex.py b/sphinx/builders/latex.py
index fadafb699..53269da07 100644
--- a/sphinx/builders/latex.py
+++ b/sphinx/builders/latex.py
@@ -322,3 +322,9 @@ def setup(app):
                          None)
     # now deprecated - use latex_elements
     app.add_config_value('latex_preamble', '', None)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/builders/linkcheck.py b/sphinx/builders/linkcheck.py
index 836709375..dbb60b344 100644
--- a/sphinx/builders/linkcheck.py
+++ b/sphinx/builders/linkcheck.py
@@ -321,3 +321,9 @@ def setup(app):
     # Anchors starting with ! are ignored since they are
     # commonly used for dynamic pages
     app.add_config_value('linkcheck_anchors_ignore', ["^!"], None)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/builders/manpage.py b/sphinx/builders/manpage.py
index a208ac74e..f688a38d9 100644
--- a/sphinx/builders/manpage.py
+++ b/sphinx/builders/manpage.py
@@ -111,3 +111,9 @@ def setup(app):
                                         '%s %s' % (self.project, self.release), [], 1)],
                          None)
     app.add_config_value('man_show_urls', False, None)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/builders/qthelp.py b/sphinx/builders/qthelp.py
index 18764b7fb..d8f43ea45 100644
--- a/sphinx/builders/qthelp.py
+++ b/sphinx/builders/qthelp.py
@@ -325,3 +325,9 @@ def setup(app):
     app.add_config_value('qthelp_basename', lambda self: make_filename(self.project), None)
     app.add_config_value('qthelp_theme', 'nonav', 'html')
     app.add_config_value('qthelp_theme_options', {}, 'html')
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/builders/texinfo.py b/sphinx/builders/texinfo.py
index 61b5d4e77..eee4f931a 100644
--- a/sphinx/builders/texinfo.py
+++ b/sphinx/builders/texinfo.py
@@ -257,3 +257,9 @@ def setup(app):
     app.add_config_value('texinfo_domain_indices', True, None, [list])
     app.add_config_value('texinfo_show_urls', 'footnote', None)
     app.add_config_value('texinfo_no_detailmenu', False, None)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/builders/text.py b/sphinx/builders/text.py
index e14ce215b..d9616d6b5 100644
--- a/sphinx/builders/text.py
+++ b/sphinx/builders/text.py
@@ -76,3 +76,9 @@ def setup(app):
 
     app.add_config_value('text_sectionchars', '*=-~"+`', 'env')
     app.add_config_value('text_newlines', 'unix', 'env')
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index d8ff5ad8d..1154b3419 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -169,3 +169,9 @@ class WebSupportBuilder(PickleHTMLBuilder):
 
 def setup(app):
     app.add_builder(WebSupportBuilder)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/builders/xml.py b/sphinx/builders/xml.py
index e0e33312c..73d9e72be 100644
--- a/sphinx/builders/xml.py
+++ b/sphinx/builders/xml.py
@@ -102,3 +102,9 @@ def setup(app):
     app.add_builder(PseudoXMLBuilder)
 
     app.add_config_value('xml_pretty', True, 'env')
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/directives/__init__.py b/sphinx/directives/__init__.py
index ea09daff5..6c1081624 100644
--- a/sphinx/directives/__init__.py
+++ b/sphinx/directives/__init__.py
@@ -248,3 +248,9 @@ def setup(app):
     directives.register_directive('describe', ObjectDescription)
     # new, more consistent, name
     directives.register_directive('object', ObjectDescription)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/directives/code.py b/sphinx/directives/code.py
index e401a50de..c6280b927 100644
--- a/sphinx/directives/code.py
+++ b/sphinx/directives/code.py
@@ -395,3 +395,9 @@ def setup(app):
     directives.register_directive('code-block', CodeBlock)
     directives.register_directive('sourcecode', CodeBlock)
     directives.register_directive('literalinclude', LiteralInclude)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py
index 15944668e..1bdef5ebc 100644
--- a/sphinx/directives/other.py
+++ b/sphinx/directives/other.py
@@ -449,3 +449,9 @@ def setup(app):
     directives.register_directive('cssclass', Class)
     # new standard name when default-domain with "class" is in effect
     directives.register_directive('rst-class', Class)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/directives/patches.py b/sphinx/directives/patches.py
index 041bee360..8b14ba2b0 100644
--- a/sphinx/directives/patches.py
+++ b/sphinx/directives/patches.py
@@ -58,3 +58,9 @@ class Meta(html.Meta):
 def setup(app):
     directives.register_directive('figure', Figure)
     directives.register_directive('meta', Meta)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/domains/c.py b/sphinx/domains/c.py
index cf4c23d5d..a9655c661 100644
--- a/sphinx/domains/c.py
+++ b/sphinx/domains/c.py
@@ -327,3 +327,9 @@ class CDomain(Domain):
 def setup(app):
     # type: (Sphinx) -> None
     app.add_domain(CDomain)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/domains/cpp.py b/sphinx/domains/cpp.py
index 5eeabcb11..acafe6a59 100644
--- a/sphinx/domains/cpp.py
+++ b/sphinx/domains/cpp.py
@@ -4992,3 +4992,9 @@ def setup(app):
     app.add_config_value("cpp_index_common_prefix", [], 'env')
     app.add_config_value("cpp_id_attributes", [], 'env')
     app.add_config_value("cpp_paren_attributes", [], 'env')
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/domains/javascript.py b/sphinx/domains/javascript.py
index 5c2eead01..a2c10af94 100644
--- a/sphinx/domains/javascript.py
+++ b/sphinx/domains/javascript.py
@@ -257,3 +257,9 @@ class JavaScriptDomain(Domain):
 def setup(app):
     # type: (Sphinx) -> None
     app.add_domain(JavaScriptDomain)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py
index 4f0d0f1ae..727e69369 100644
--- a/sphinx/domains/python.py
+++ b/sphinx/domains/python.py
@@ -844,3 +844,9 @@ class PythonDomain(Domain):
 def setup(app):
     # type: (Sphinx) -> None
     app.add_domain(PythonDomain)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/domains/rst.py b/sphinx/domains/rst.py
index fa3353aa6..b433e83c6 100644
--- a/sphinx/domains/rst.py
+++ b/sphinx/domains/rst.py
@@ -179,3 +179,9 @@ class ReSTDomain(Domain):
 def setup(app):
     # type: (Sphinx) -> None
     app.add_domain(ReSTDomain)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/domains/std.py b/sphinx/domains/std.py
index 53305899d..3eaf69845 100644
--- a/sphinx/domains/std.py
+++ b/sphinx/domains/std.py
@@ -912,3 +912,9 @@ class StandardDomain(Domain):
 def setup(app):
     # type: (Sphinx) -> None
     app.add_domain(StandardDomain)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/environment/__init__.py b/sphinx/environment/__init__.py
index 27939db0d..4473b801d 100644
--- a/sphinx/environment/__init__.py
+++ b/sphinx/environment/__init__.py
@@ -428,7 +428,7 @@ class BuildEnvironment(object):
             return rel_fn, path.abspath(path.join(self.srcdir, enc_rel_fn))
 
     def find_files(self, config):
-        # type: (Config) -> None
+        # type: (Config, unicode) -> None
         """Find all source files in the source dir and put them in
         self.found_docs.
         """
@@ -446,16 +446,23 @@ class BuildEnvironment(object):
             else:
                 self.warn(docname, "document not readable. Ignored.")
 
-        # add catalog mo file dependency
-        for docname in self.found_docs:
-            catalog_files = find_catalog_files(
-                docname,
-                self.srcdir,
-                self.config.locale_dirs,
-                self.config.language,
-                self.config.gettext_compact)
-            for filename in catalog_files:
-                self.dependencies.setdefault(docname, set()).add(filename)
+        # Current implementation is applying translated messages in the reading
+        # phase.Therefore, in order to apply the updated message catalog, it is
+        # necessary to re-process from the reading phase. Here, if dependency
+        # is set for the doc source and the mo file, it is processed again from
+        # the reading phase when mo is updated. In the future, we would like to
+        # move i18n process into the writing phase, and remove these lines.
+        if buildername != 'gettext':
+            # add catalog mo file dependency
+            for docname in self.found_docs:
+                catalog_files = find_catalog_files(
+                    docname,
+                    self.srcdir,
+                    self.config.locale_dirs,
+                    self.config.language,
+                    self.config.gettext_compact)
+                for filename in catalog_files:
+                    self.dependencies.setdefault(docname, set()).add(filename)
 
     def get_outdated_files(self, config_changed):
         # type: (bool) -> Tuple[Set[unicode], Set[unicode], Set[unicode]]
@@ -539,7 +546,7 @@ class BuildEnvironment(object):
         # the source and doctree directories may have been relocated
         self.srcdir = srcdir
         self.doctreedir = doctreedir
-        self.find_files(config)
+        self.find_files(config, app.buildername)
         self.config = config
 
         # this cache also needs to be updated every time
diff --git a/sphinx/environment/managers/indexentries.py b/sphinx/environment/managers/indexentries.py
index 8cf20f480..11e5ccbb0 100644
--- a/sphinx/environment/managers/indexentries.py
+++ b/sphinx/environment/managers/indexentries.py
@@ -126,7 +126,11 @@ class IndexEntries(EnvironmentManager):
         # 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())
+            key, (void, void, category_key) = entry
+            if category_key:
+                # using specified category key to sort
+                key = category_key
+            lckey = unicodedata.normalize('NFD', key.lower())
             if lckey[0:1] in lcletters:
                 lckey = chr(127) + lckey
             # ensure a determinstic order *within* letters by also sorting on
diff --git a/sphinx/roles.py b/sphinx/roles.py
index 01e34fa71..182a3db21 100644
--- a/sphinx/roles.py
+++ b/sphinx/roles.py
@@ -349,3 +349,9 @@ def setup(app):
 
     for rolename, func in iteritems(specific_docroles):
         roles.register_local_role(rolename, func)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py
index 76ad8dea1..ebffa2f28 100644
--- a/sphinx/writers/html.py
+++ b/sphinx/writers/html.py
@@ -22,7 +22,6 @@ from docutils.writers.html4css1 import Writer, HTMLTranslator as BaseTranslator
 from sphinx import addnodes
 from sphinx.deprecation import RemovedInSphinx16Warning
 from sphinx.locale import admonitionlabels, _
-import sphinx.util.docutils
 from sphinx.util.images import get_image_size
 from sphinx.util.smartypants import sphinx_smarty_pants
 
@@ -535,13 +534,10 @@ class HTMLTranslator(BaseTranslator):
 
     # overwritten
     def depart_image(self, node):
-        if sphinx.util.docutils.__version_info__ >= (0, 13):
-            # since docutils-0.13, HTMLWriter does not push context data on visit_image()
-            if node['uri'].lower().endswith(('svg', 'svgz')):
-                self.body.append(self.context.pop())
-        else:
-            # docutils-0.12 or below, HTML Writer always push context data on visit_image()
+        if node['uri'].lower().endswith(('svg', 'svgz')):
             self.body.append(self.context.pop())
+        else:
+            BaseTranslator.depart_image(self, node)
 
     def visit_toctree(self, node):
         # this only happens when formatting a toc from env.tocs -- in this
diff --git a/tests/test_intl.py b/tests/test_intl.py
index 68fae6b15..4a517c111 100644
--- a/tests/test_intl.py
+++ b/tests/test_intl.py
@@ -367,6 +367,15 @@ def test_gettext_builder(app, status, warning):
     for expect_msg in [m for m in expect if m.id]:
         yield assert_in, expect_msg.id, [m.id for m in actual if m.id]
 
+    # --- don't rebuild by .mo mtime
+    app.builder.build_update()
+    updated = app.env.update(app.config, app.srcdir, app.doctreedir, app)
+    yield assert_equal, len(updated), 0
+
+    (app.srcdir / 'xx' / 'LC_MESSAGES' / 'bom.mo').utime(None)
+    updated = app.env.update(app.config, app.srcdir, app.doctreedir, app)
+    yield assert_equal, len(updated), 0
+
 
 @gen_with_intl_app('html', freshenv=True)
 def test_html_builder(app, status, warning):