Merge branch 'master' into deprecate_sphinx.util.compat

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,27 @@
+Subject: <what happen when you do on which document project>
+
+# Problem
+- <Detail of problem>
+
+## Procedure to reproduce the problem
+```
+<Paste your command-line here which cause the problem>
+```
+
+## Error logs / results
+```
+<Paste your error log here>
+```
+- <public link of unexpected result if you have>
+
+## Expected results
+<Describe what to actually do>
+
+# Reproducible project / your project
+- <link to your project, or attach zipped small project sample>
+
+# Environment info
+- OS: <Unix/Linux/Mac/Win/other with version>
+- Python version:
+- Sphinx version:
+- <Extra tools e.g.: Browser, tex or something else>

CHANGES

@@ -4,6 +4,9 @@ Release 1.6 (in development)
 Incompatible changes
 --------------------
 
+* #1061, #2336, #3235: Now generation of autosummary doesn't contain imported
+  members by default. Thanks to Luc Saffre.
+
 Features added
 --------------
 
@@ -19,8 +22,17 @@ Deprecated
   ``docutils.parsers.rsr.Directive``
 * ``sphinx.util.compat.docutils_version`` is now deprecated
 
-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
 --------------
@@ -42,6 +54,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)
 ==================================

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
 

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'

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,
+    }

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,
+    }

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,
+    }

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,
+    }

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,
+    }

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,
+    }

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,
+    }

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,
+    }

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,
+    }

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,
+    }

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,
+    }

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,
+    }

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,
+    }

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,
+    }

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,
+    }

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,
+    }

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,
+    }

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,
+    }

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,
+    }

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,
+    }

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,
+    }

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,
+    }

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,
+    }

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,
+    }

sphinx/domains/python.py

@@ -843,3 +843,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,
+    }

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,
+    }

sphinx/domains/std.py

@@ -911,3 +911,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,
+    }

sphinx/environment/__init__.py

@@ -427,8 +427,8 @@ class BuildEnvironment(object):
             enc_rel_fn = rel_fn.encode(sys.getfilesystemencoding())
             return rel_fn, path.abspath(path.join(self.srcdir, enc_rel_fn))
 
-    def find_files(self, config):
-        # type: (Config) -> None
+    def find_files(self, config, buildername):
+        # 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

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

sphinx/ext/autosummary/generate.py

@@ -165,17 +165,18 @@ def generate_autosummary_docs(sources, output_dir=None, suffix='.rst',
                 except TemplateNotFound:
                     template = template_env.get_template('autosummary/base.rst')
 
-            def get_members(obj, typ, include_public=[]):
+            def get_members(obj, typ, include_public=[], imported=False):
                 # type: (Any, unicode, List[unicode]) -> Tuple[List[unicode], List[unicode]]
                 items = []  # type: List[unicode]
                 for name in dir(obj):
                     try:
-                        documenter = get_documenter(safe_getattr(obj, name),
-                                                    obj)
+                        value = safe_getattr(obj, name)
                     except AttributeError:
                         continue
+                    documenter = get_documenter(value, obj)
                     if documenter.objtype == typ:
-                        items.append(name)
+                        if imported or getattr(value, '__module__', None) == obj.__name__:
+                            items.append(name)
                 public = [x for x in items
                           if x in include_public or not x.startswith('_')]
                 return public, items

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,
+    }

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

sphinx/writers/latex.py

@@ -2179,10 +2179,11 @@ class LaTeXTranslator(nodes.NodeVisitor):
                                         '\\begin{sphinxVerbatim}')
             # get consistent trailer
             hlcode = hlcode.rstrip()[:-14]  # strip \end{Verbatim}
-            self.body.append('\n' + hlcode + '\\end{sphinxVerbatim')
             if self.table and not self.in_footnote:
-                self.body.append('intable')
-            self.body.append('}\n')
+                hlcode += '\\end{sphinxVerbatimintable}'
+            else:
+                hlcode += '\\end{sphinxVerbatim}'
+            self.body.append('\n' + hlcode + '\n')
             if ids:
                 self.body.append('\\let\\sphinxLiteralBlockLabel\\empty\n')
             raise nodes.SkipNode

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