Merge branch 'stable'

.gitignore

@@ -21,6 +21,7 @@ build/
 dist/
 Sphinx.egg-info/
 doc/_build/
+doc/locale/
 tests/.coverage
 tests/build/
 utils/regression_test.js

CHANGES

@@ -101,6 +101,22 @@ Bugs fixed
 * :pep: and :rfc: does not supports ``default-role`` directive (refs: #3960)
 * #3960: default_role = 'guilabel' not functioning
 * Missing ``texinputs_win/Makefile`` to be used in latexpdf builder on windows.
+* #4026: nature: Fix macOS Safari scrollbar color
+* #3877: Fix for C++ multiline signatures.
+* #4006: Fix crash on parallel build
+* #3969: private instance attributes causes AttributeError
+* #4041: C++, remove extra name linking in function pointers.
+* #4038: C, add missing documentation of ``member`` role.
+* #4044: An empty multicolumn cell causes extra row height in PDF output
+* #4049: Fix typo in output of sphinx-build -h
+* #4062: hashlib.sha1() must take bytes, not unicode on Python 3
+* Avoid indent after index entries in latex (refs: #4066)
+* #4070: crashes when the warning message contains format strings
+* #4067: Return non-zero exit status when make subprocess fails
+* #4055: graphviz: the :align: option does not work for SVG output
+* #4055: graphviz: the :align: center option does not work for latex output
+
+
 
 Testing
 --------

doc/builders.rst

@@ -403,8 +403,8 @@ instructions.
 .. class:: CheckExternalLinksBuilder
 
    This builder scans all documents for external links, tries to open them with
-   :mod:`urllib2`, and writes an overview which ones are broken and redirected
-   to standard output and to :file:`output.txt` in the output directory.
+   ``requests``, and writes an overview which ones are broken and redirected to
+   standard output and to :file:`output.txt` in the output directory.
 
    .. autoattribute:: name
 
@@ -412,6 +412,10 @@ instructions.
 
    .. autoattribute:: supported_image_types
 
+   .. versionchanged:: 1.5
+
+      Since Sphinx-1.5, the linkcheck builder comes to use requests module.
+
 .. module:: sphinx.builders.xml
 .. class:: XMLBuilder
 

doc/domains.rst

@@ -473,7 +473,7 @@ The C Domain
 
 The C domain (name **c**) is suited for documentation of C API.
 
-.. rst:directive:: .. c:function:: type name(signature)
+.. rst:directive:: .. c:function:: function prototype
 
    Describes a C function. The signature should be given as in C, e.g.::
 
@@ -485,7 +485,7 @@ The C domain (name **c**) is suited for documentation of C API.
    Note that you don't have to backslash-escape asterisks in the signature, as
    it is not parsed by the reST inliner.
 
-.. rst:directive:: .. c:member:: type name
+.. rst:directive:: .. c:member:: declaration
 
    Describes a C struct member. Example signature::
 
@@ -508,7 +508,7 @@ The C domain (name **c**) is suited for documentation of C API.
    Describes a C type (whether defined by a typedef or struct). The signature
    should just be the type name.
 
-.. rst:directive:: .. c:var:: type name
+.. rst:directive:: .. c:var:: declaration
 
    Describes a global C variable.  The signature should include the type, such
    as::
@@ -524,14 +524,14 @@ Cross-referencing C constructs
 The following roles create cross-references to C-language constructs if they are
 defined in the documentation:
 
-.. rst:role:: c:data
-
-   Reference a C-language variable.
-
 .. rst:role:: c:func
 
    Reference a C-language function. Should include trailing parentheses.
 
+.. rst:role:: c:member
+
+   Reference a C-language member of a struct.
+
 .. rst:role:: c:macro
 
    Reference a "simple" C macro, as defined above.
@@ -540,6 +540,10 @@ defined in the documentation:
 
    Reference a C-language type.
 
+.. rst:role:: c:data
+
+   Reference a C-language variable.
+
 .. _cpp-domain:
 
 The C++ Domain

doc/tutorial.rst

@@ -153,9 +153,9 @@ very general sense) in any :dfn:`domain`.  A domain is a collection of object
 types that belong together, complete with markup to create and reference
 descriptions of these objects.
 
-The most prominent domain is the Python domain.  To e.g. document the Python
-built-in function ``enumerate()``, you would add this to one of your source
-files::
+The most prominent domain is the Python domain. For example, to document
+Python's built-in function ``enumerate()``, you would add this to one of your
+source files::
 
    .. py:function:: enumerate(sequence[, start=0])
 

sphinx/domains/cpp.py

@@ -2703,6 +2703,10 @@ class ASTType(ASTBase):
         if (self.decl.require_space_after_declSpecs() and
                 len(text_type(self.declSpecs)) > 0):
             signode += nodes.Text(' ')
+        # for paramters that don't really declare new names we get 'markType',
+        # this should not be propagated, but be 'noneIsName'.
+        if mode == 'markType':
+            mode = 'noneIsName'
         self.decl.describe_signature(signode, mode, env, symbol)
 
 
@@ -5206,8 +5210,11 @@ class CPPObject(ObjectDescription):
         if ast.objectType == 'enumerator':
             self._add_enumerator_to_parent(ast)
 
-        self.options['tparam-line-spec'] = 'tparam-line-spec' in self.options
-        self.describe_signature(signode, ast, self.options)
+        # note: handle_signature may be called multiple time per directive,
+        # if it has multiple signatures, so don't mess with the original options.
+        options = dict(self.options)
+        options['tparam-line-spec'] = 'tparam-line-spec' in self.options
+        self.describe_signature(signode, ast, options)
         return ast
 
     def before_content(self):
@@ -5462,12 +5469,12 @@ class CPPDomain(Domain):
     name = 'cpp'
     label = 'C++'
     object_types = {
-        'class': ObjType(l_('class'), 'class'),
-        'function': ObjType(l_('function'), 'func'),
-        'member': ObjType(l_('member'), 'member'),
-        'type': ObjType(l_('type'), 'type'),
-        'concept': ObjType(l_('concept'), 'concept'),
-        'enum': ObjType(l_('enum'), 'enum'),
+        'class':      ObjType(l_('class'),      'class',             'type', 'typeOrConcept'),
+        'function':   ObjType(l_('function'),   'function',  'func', 'type', 'typeOrConcept'),
+        'member':     ObjType(l_('member'),     'member',    'var'),
+        'type':       ObjType(l_('type'),                            'type', 'typeOrConcept'),
+        'concept':    ObjType(l_('concept'),    'concept',                   'typeOrConcept'),
+        'enum':       ObjType(l_('enum'),       'enum',              'type', 'typeOrConcept'),
         'enumerator': ObjType(l_('enumerator'), 'enumerator')
     }
 
@@ -5605,16 +5612,10 @@ class CPPDomain(Domain):
                 return True
             if declTyp == 'templateParam':
                 return True
-            if typ == 'var' or typ == 'member':
-                return declTyp in ['var', 'member']
-            if typ in ['enum', 'enumerator', 'function', 'class', 'concept']:
-                return declTyp == typ
-            validForType = ['enum', 'class', 'function', 'type']
-            if typ == 'typeOrConcept':
-                return declTyp == 'concept' or declTyp in validForType
-            if typ == 'type':
-                return declTyp in validForType
-            print("Type is %s" % typ)
+            objtypes = self.objtypes_for_role(typ)
+            if objtypes and declTyp in objtypes:
+                return True
+            print("Type is %s, declType is %s" % (typ, declTyp))
             assert False
         if not checkType():
             warner.warn("cpp:%s targets a %s (%s)."

sphinx/ext/autodoc/__init__.py

@@ -707,14 +707,20 @@ class Documenter(object):
                     self.options.special_members is not ALL and \
                         membername in self.options.special_members:
                     keep = has_doc or self.options.undoc_members
+            elif (namespace, membername) in attr_docs:
+                if want_all and membername.startswith('_'):
+                    # ignore members whose name starts with _ by default
+                    keep = self.options.private_members and \
+                        (has_doc or self.options.undoc_members)
+                else:
+                    # keep documented attributes
+                    keep = True
+                isattr = True
+                print(membername, keep)
             elif want_all and membername.startswith('_'):
                 # ignore members whose name starts with _ by default
                 keep = self.options.private_members and \
                     (has_doc or self.options.undoc_members)
-            elif (namespace, membername) in attr_docs:
-                # keep documented attributes
-                keep = True
-                isattr = True
             else:
                 # ignore undocumented members if :undoc-members: is not given
                 keep = has_doc or self.options.undoc_members

sphinx/make_mode.py

@@ -18,6 +18,7 @@ from __future__ import print_function
 
 import os
 import sys
+import subprocess
 from os import path
 
 import sphinx
@@ -196,16 +197,14 @@ class Make(object):
         if self.run_generic_build('latex') > 0:
             return 1
         with cd(self.builddir_join('latex')):
-            os.system('%s all-pdf' % self.makecmd)
-        return 0
+            return subprocess.call([self.makecmd, 'all-pdf'])
 
     def build_latexpdfja(self):
         # type: () -> int
         if self.run_generic_build('latex') > 0:
             return 1
         with cd(self.builddir_join('latex')):
-            os.system('%s all-pdf-ja' % self.makecmd)
-        return 0
+            return subprocess.call([self.makecmd, 'all-pdf-ja'])
 
     def build_text(self):
         # type: () -> int
@@ -231,8 +230,7 @@ class Make(object):
         if self.run_generic_build('texinfo') > 0:
             return 1
         with cd(self.builddir_join('texinfo')):
-            os.system('%s info' % self.makecmd)
-        return 0
+            return subprocess.call([self.makecmd, 'info'])
 
     def build_gettext(self):
         # type: () -> int

sphinx/themes/nature/static/nature.css_t

@@ -16,7 +16,7 @@
 body {
     font-family: Arial, sans-serif;
     font-size: 100%;
-    background-color: #111;
+    background-color: #fff;
     color: #555;
     margin: 0;
     padding: 0;

sphinx/util/logging.py

@@ -356,10 +356,11 @@ class WarningIsErrorFilter(logging.Filter):
             return True
         elif self.app.warningiserror:
             location = getattr(record, 'location', '')
+            message = record.msg.replace('%', '%%')
             if location:
-                raise SphinxWarning(location + ":" + record.msg % record.args)
+                raise SphinxWarning(location + ":" + message % record.args)
             else:
-                raise SphinxWarning(record.msg % record.args)
+                raise SphinxWarning(message % record.args)
         else:
             return True
 

sphinx/util/parallel.py

@@ -122,6 +122,7 @@ class ParallelTasks(object):
                     logger.handle(log)
                 self._result_funcs.pop(tid)(self._args.pop(tid), result)
                 self._procs[tid].join()
+                self._precvs.pop(tid)
                 self._pworking -= 1
                 break
         else:

sphinx/writers/latex.py

@@ -1462,7 +1462,8 @@ class LaTeXTranslator(nodes.NodeVisitor):
         if cell.width > 1 or cell.height > 1:
             self.body.append('\\begin{varwidth}[t]{\\sphinxcolwidth{%d}{%d}}\n'
                              % (cell.width, self.table.colcount))
-            context = ('\\par\n\\vskip-\\baselineskip\\strut\\end{varwidth}%\n') + context
+            context = ('\\par\n\\vskip-\\baselineskip'
+                       '\\vbox{\\hbox{\\strut}}\\end{varwidth}%\n') + context
             self.needs_linetrimming = 1
         if len(node) > 2 and len(node.astext().split('\n')) > 2:
             self.needs_linetrimming = 1
@@ -2005,6 +2006,8 @@ class LaTeXTranslator(nodes.NodeVisitor):
                     logger.warning('unknown index entry type %s found', type)
             except ValueError as err:
                 logger.warning(str(err))
+        if not node.get('inline', True):
+            self.body.append('\\ignorespaces ')
         raise nodes.SkipNode
 
     def visit_raw(self, node):

tests/roots/test-ext-intersphinx-cppdomain/index.rst

@@ -4,3 +4,5 @@ test-ext-intersphinx-cppdomain
 .. cpp:namespace:: foo
 
 :cpp:class:`Bar`
+
+.. cpp:function:: std::uint8_t FooBarBaz()

tests/roots/test-latex-index/conf.py

@@ -0,0 +1,3 @@
+# -*- coding: utf-8 -*-
+
+master_doc = 'index'

tests/roots/test-latex-index/index.rst

@@ -0,0 +1,12 @@
+test-latex-index
+================
+
+A :index:`famous` :index:`equation`:
+
+.. math::
+
+   E = m c^2
+
+.. index:: Einstein, relativity
+
+and some text.

tests/roots/test-latex-table/expects/complex_spanning_cell.tex

@@ -18,13 +18,13 @@ consecutive multirow at end of row (1-4 and 1-5)
 \begin{varwidth}[t]{\sphinxcolwidth{1}{5}}
 cell1-1
 \par
-\vskip-\baselineskip\strut\end{varwidth}%
+\vskip-\baselineskip\vbox{\hbox{\strut}}\end{varwidth}%
 }%
 &\sphinxmultirow{3}{2}{%
 \begin{varwidth}[t]{\sphinxcolwidth{1}{5}}
 cell1-2
 \par
-\vskip-\baselineskip\strut\end{varwidth}%
+\vskip-\baselineskip\vbox{\hbox{\strut}}\end{varwidth}%
 }%
 &
 cell1-3
@@ -32,20 +32,20 @@ cell1-3
 \begin{varwidth}[t]{\sphinxcolwidth{1}{5}}
 cell1-4
 \par
-\vskip-\baselineskip\strut\end{varwidth}%
+\vskip-\baselineskip\vbox{\hbox{\strut}}\end{varwidth}%
 }%
 &\sphinxmultirow{2}{5}{%
 \begin{varwidth}[t]{\sphinxcolwidth{1}{5}}
 cell1-5
 \par
-\vskip-\baselineskip\strut\end{varwidth}%
+\vskip-\baselineskip\vbox{\hbox{\strut}}\end{varwidth}%
 }%
 \\
 \cline{3-3}\sphinxtablestrut{1}&\sphinxtablestrut{2}&\sphinxmultirow{2}{6}{%
 \begin{varwidth}[t]{\sphinxcolwidth{1}{5}}
 cell2-3
 \par
-\vskip-\baselineskip\strut\end{varwidth}%
+\vskip-\baselineskip\vbox{\hbox{\strut}}\end{varwidth}%
 }%
 &\sphinxtablestrut{4}&\sphinxtablestrut{5}\\
 \cline{5-5}\sphinxtablestrut{1}&\sphinxtablestrut{2}&\sphinxtablestrut{6}&\sphinxtablestrut{4}&

tests/roots/test-latex-table/expects/gridtable.tex

@@ -17,7 +17,7 @@ cell1-1
 \begin{varwidth}[t]{\sphinxcolwidth{1}{3}}
 cell1-2
 \par
-\vskip-\baselineskip\strut\end{varwidth}%
+\vskip-\baselineskip\vbox{\hbox{\strut}}\end{varwidth}%
 }%
 &
 cell1-3
@@ -26,7 +26,7 @@ cell1-3
 \begin{varwidth}[t]{\sphinxcolwidth{1}{3}}
 cell2-1
 \par
-\vskip-\baselineskip\strut\end{varwidth}%
+\vskip-\baselineskip\vbox{\hbox{\strut}}\end{varwidth}%
 }%
 &\sphinxtablestrut{5}&
 cell2-3
@@ -36,7 +36,7 @@ cell2-3
 \begin{varwidth}[t]{\sphinxcolwidth{2}{3}}
 cell3-2
 \par
-\vskip-\baselineskip\strut\end{varwidth}%
+\vskip-\baselineskip\vbox{\hbox{\strut}}\end{varwidth}%
 }%
 \sphinxstopmulticolumn
 \\
@@ -47,7 +47,7 @@ cell4-1
 \begin{varwidth}[t]{\sphinxcolwidth{3}{3}}
 cell5-1
 \par
-\vskip-\baselineskip\strut\end{varwidth}%
+\vskip-\baselineskip\vbox{\hbox{\strut}}\end{varwidth}%
 \sphinxstopmulticolumn
 \\
 \hline

tests/test_autodoc.py

@@ -107,7 +107,7 @@ def process_signature(app, what, name, obj, options, args, retann):
 def skip_member(app, what, name, obj, skip, options):
     if name in ('__special1__', '__special2__'):
         return skip
-    if name.startswith('_'):
+    if name.startswith('__'):
         return True
     if name == 'skipmeth':
         return True
@@ -763,6 +763,7 @@ def test_generate():
 
     # test autodoc_member_order == 'source'
     directive.env.ref_context['py:module'] = 'test_autodoc'
+    options.private_members = True
     if PY3:
         roger_line = '   .. py:classmethod:: Class.roger(a, *, b=2, c=3, d=4, e=5, f=6)'
     else:
@@ -780,6 +781,7 @@ def test_generate():
                   '   .. py:classmethod:: Class.moore(a, e, f) -> happiness',
                   '   .. py:attribute:: Class.inst_attr_comment',
                   '   .. py:attribute:: Class.inst_attr_string',
+                  '   .. py:attribute:: Class._private_inst_attr',
                   '   .. py:method:: Class.inheritedmeth()',
                   ],
                  'class', 'Class', member_order='bysource', all_members=True)
@@ -1002,6 +1004,7 @@ class Class(Base):
         self.inst_attr_comment = None
         self.inst_attr_string = None
         """a documented instance attribute"""
+        self._private_inst_attr = None  #: a private instance attribute
 
     def __special1__(self):
         """documented special method"""

tests/test_build_latex.py

@@ -1019,3 +1019,12 @@ def test_latex_remote_images(app, status, warning):
     assert '\\sphinxincludegraphics{{NOT_EXIST}.PNG}' not in result
     assert ('WARNING: Could not fetch remote image: '
             'http://example.com/NOT_EXIST.PNG [404]' in warning.getvalue())
+
+
+@pytest.mark.sphinx('latex', testroot='latex-index')
+def test_latex_index(app, status, warning):
+    app.builder.build_all()
+
+    result = (app.outdir / 'Python.tex').text(encoding='utf8')
+    assert 'A \\index{famous}famous \\index{equation}equation:\n' in result
+    assert '\n\\index{Einstein}\\index{relativity}\\ignorespaces \nand' in result

tests/test_ext_intersphinx.py

@@ -232,6 +232,12 @@ def test_missing_reference_cppdomain(tempdir, app, status, warning):
             ' href="https://docs.python.org/index.html#cpp_foo_bar"'
             ' title="(in foo v2.0)"><code class="xref cpp cpp-class docutils literal">'
             '<span class="pre">Bar</span></code></a>' in html)
+    assert ('<a class="reference external"'
+            ' href="https://docs.python.org/index.html#std"'
+            ' title="(in foo v2.0)">std</a>' in html)
+    assert ('<a class="reference external"'
+            ' href="https://docs.python.org/index.html#std_uint8_t"'
+            ' title="(in foo v2.0)">uint8_t</a>' in html)
 
 
 def test_missing_reference_jsdomain(tempdir, app, status, warning):

tests/test_util_inventory.py

@@ -34,6 +34,8 @@ module1 py:module 0 foo.html#module-module1 Long Module desc
 module2 py:module 0 foo.html#module-$ -
 module1.func py:function 1 sub/foo.html#$ -
 CFunc c:function 2 cfunc.html#CFunc -
+std cpp:type 1 index.html#std -
+std::uint8_t cpp:type 1 index.html#std_uint8_t -
 foo::Bar cpp:class 1 index.html#cpp_foo_bar -
 foo::Bar::baz cpp:function 1 index.html#cpp_foo_bar_baz -
 a term std:term -1 glossary.html#term-a-term -