Merge branch 'master' into 4362_dont_overwrite_latex

CHANGES

@@ -34,7 +34,7 @@ Incompatible changes
 * #1857: latex: :confval:`latex_show_pagerefs` does not add pagerefs for
   citations
 * #4648: latex: Now "rubric" elements are rendered as unnumbered section title
-* #4983: html: The URL for the productionlist has been changed
+* #4983: html: The anchor for productionlist tokens has been changed
 * Modifying a template variable ``script_files`` in templates is allowed now.
   Please use ``app.add_js_file()`` instead.
 
@@ -137,6 +137,8 @@ Features added
 * html: Output ``canonical_url`` metadata if :confval:`html_baseurl` set (refs:
   #4193)
 * #5029: autosummary: expose ``inherited_members`` to template
+* #3784: mathjax: Add :confval:`mathjax_options` to give options to script tag
+  for mathjax
 * #4362: latex: Don't overwrite .tex file if document not changed
 
 Bugs fixed
@@ -156,6 +158,11 @@ Features removed
 
 * ``sphinx.ext.pngmath`` extension
 
+Documentation
+-------------
+
+* #5083: Fix wrong make.bat option for internationalization.
+
 Release 1.7.6 (in development)
 ==============================
 
@@ -180,6 +187,13 @@ Bugs fixed
 * #5022: latex: crashed with docutils package provided by Debian/Ubuntu
 * #5009: latex: a label for table is vanished if table does not have a caption
 * #5048: crashed with numbered toctree
+* #2410: C, render empty argument lists for macros.
+* C++, fix lookup of full template specializations with no template arguments.
+* #4667: C++, fix assertion on missing references in global scope when using
+  intersphinx. Thanks to Alan M. Carroll.
+* #5019: autodoc: crashed by Form Feed Character
+* #5032: autodoc: loses the first staticmethod parameter for old styled classes
+* #5036: quickstart: Typing Ctrl-U clears the whole of line
 
 Testing
 --------

EXAMPLES

@@ -195,6 +195,7 @@ Documentation using sphinx_rtd_theme
 * Julia: https://julia.readthedocs.io/
 * Jupyter Notebook: https://jupyter-notebook.readthedocs.io/
 * Lasagne: https://lasagne.readthedocs.io/
+* latexindent.pl: https://latexindentpl.readthedocs.io/
 * Linguistica: https://linguistica-uchicago.github.io/lxa5/
 * Linux kernel: https://www.kernel.org/doc/html/latest/index.html
 * MathJax: https://docs.mathjax.org/
@@ -218,6 +219,7 @@ Documentation using sphinx_rtd_theme
 * peewee: http://docs.peewee-orm.com/
 * Phinx: http://docs.phinx.org/
 * phpMyAdmin: https://docs.phpmyadmin.net/
+* PROS: https://pros.cs.purdue.edu/v5/ (customized)
 * Pweave: http://mpastell.com/pweave/
 * PyPy: http://doc.pypy.org/
 * python-sqlparse: https://sqlparse.readthedocs.io/

doc/Makefile

@@ -1,9 +1,10 @@
 # Makefile for Sphinx documentation
 #
+PYTHON ?= python
 
 # You can set these variables from the command line.
 SPHINXOPTS   =
-SPHINXBUILD  = python3 ../sphinx/cmd/build.py
+SPHINXBUILD  = $(PYTHON) ../sphinx/cmd/build.py
 SPHINXPROJ   = sphinx
 SOURCEDIR    = .
 BUILDDIR     = _build

doc/ext/autodoc.rst

@@ -41,7 +41,7 @@ you can also enable the :mod:`napoleon <sphinx.ext.napoleon>` extension.
 docstrings to correct reStructuredText before :mod:`autodoc` processes them.
 
 .. _Google:
-   https://google.github.io/styleguide/pyguide.html#Comments
+   https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings
 .. _NumPy:
    https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
 
@@ -374,7 +374,7 @@ There are also new config values that you can set:
    This value contains a list of modules to be mocked up. This is useful when
    some external dependencies are not met at build time and break the building
    process. You may only specify the root package of the dependencies
-   themselves and ommit the sub-modules:
+   themselves and omit the sub-modules:
 
    .. code-block:: python
 

doc/ext/math.rst

@@ -260,6 +260,16 @@ Sphinx.
 
    You can also give a full ``https://`` URL different from the CDN URL.
 
+.. confval:: mathjax_options
+
+   The options to script tag for mathjax.  For example, you can set integrity
+   option with following setting::
+
+       mathjax_options = {
+           'integrity': 'sha384-......',
+       }
+
+   The default is empty (``{}``).
 
 :mod:`sphinx.ext.jsmath` -- Render math via JavaScript
 ------------------------------------------------------

doc/extdev/index.rst

@@ -101,7 +101,7 @@ Deprecated APIs
 
 On developing Sphinx, we are always careful to the compatibility of our APIs.
 But, sometimes, the change of interface are needed for some reasons.  In such
-cases, we've marked thme as deprecated. And they are kept during the two
+cases, we've marked them as deprecated. And they are kept during the two
 major versions (for more details, please see :ref:`deprecation-policy`).
 
 The following is a list of deprecated interface.

doc/intl.rst

@@ -123,14 +123,14 @@ This section describe an easy way to translate with sphinx-intl.
 
    .. code-block:: console
 
-      > set SPHINXOPTS=-D language='de'
+      > set SPHINXOPTS=-D language=de
       > .\make.bat html
 
    command line (for PowerShell):
 
    .. code-block:: console
 
-      > Set-Item env:SPHINXOPTS "-D language='de'"
+      > Set-Item env:SPHINXOPTS "-D language=de"
       > .\make.bat html
 
 

sphinx/cmd/quickstart.py

@@ -41,7 +41,7 @@ from sphinx import __display_version__, package_dir
 from sphinx.locale import __
 from sphinx.util import texescape
 from sphinx.util.console import (  # type: ignore
-    purple, bold, red, turquoise, nocolor, color_terminal
+    colorize, bold, red, turquoise, nocolor, color_terminal
 )
 from sphinx.util.osutil import ensuredir, make_filename
 from sphinx.util.template import SphinxRenderer
@@ -85,8 +85,14 @@ PROMPT_PREFIX = '> '
 # function to get input from terminal -- overridden by the test suite
 def term_input(prompt):
     # type: (unicode) -> unicode
+    if sys.platform == 'win32':
+        # Important: On windows, readline is not enabled by default.  In these
+        #            environment, escape sequences have been broken.  To avoid the
+        #            problem, quickstart uses ``print()`` to show prompt.
         print(prompt, end='')
         return input('')
+    else:
+        return input(prompt)
 
 
 class ValidationError(Exception):
@@ -186,7 +192,7 @@ def do_prompt(text, default=None, validator=nonempty):
                         prompt = prompt.encode('utf-8')
                     except UnicodeEncodeError:
                         prompt = prompt.encode('latin1')
-        prompt = purple(prompt)
+        prompt = colorize('purple', prompt, input_mode=True)
         x = term_input(prompt).strip()
         if default and not x:
             x = default

sphinx/config.py

@@ -365,7 +365,7 @@ def eval_config_file(filename, tags):
                      "called sys.exit()")
             raise ConfigError(msg)
         except Exception:
-            msg = __("There is a programable error in your configuration file:\n\n%s")
+            msg = __("There is a programmable error in your configuration file:\n\n%s")
             raise ConfigError(msg % traceback.format_exc())
 
     return namespace

sphinx/domains/c.py

@@ -147,7 +147,8 @@ class CObject(ObjectDescription):
             fullname = name
 
         if not arglist:
-            if self.objtype == 'function':
+            if self.objtype == 'function' or \
+                    self.objtype == 'macro' and sig.rstrip().endswith('()'):
                 # for functions, add an empty parameter list
                 signode += addnodes.desc_parameterlist()
             if const:

sphinx/domains/cpp.py

@@ -3566,6 +3566,9 @@ class Symbol(object):
             # and params that are packs must in the args be the name expanded
             if len(templateParams.params) != len(templateArgs.args):
                 return True
+            # having no template params and no arguments is also a specialization
+            if len(templateParams.params) == 0:
+                return True
             for i in range(len(templateParams.params)):
                 param = templateParams.params[i]
                 arg = templateArgs.args[i]

sphinx/ext/mathjax.py

@@ -74,6 +74,8 @@ def builder_inited(app):
                              'mathjax extension to work')
     if app.builder.format == 'html':
         options = {'async': 'async'}
+        if app.config.mathjax_options:
+            options.update(app.config.mathjax_options)
         app.builder.add_js_file(app.config.mathjax_path, **options)  # type: ignore
 
 
@@ -88,7 +90,8 @@ def setup(app):
     # https://docs.mathjax.org/en/latest/start.html#secure-access-to-the-cdn
     app.add_config_value('mathjax_path',
                          'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?'
-                         'config=TeX-AMS-MML_HTMLorMML', False)
+                         'config=TeX-AMS-MML_HTMLorMML', 'html')
+    app.add_config_value('mathjax_options', {}, 'html')
     app.add_config_value('mathjax_inline', [r'\(', r'\)'], 'html')
     app.add_config_value('mathjax_display', [r'\[', r'\]'], 'html')
     app.connect('builder-inited', builder_inited)

sphinx/pycode/parser.py

@@ -34,6 +34,11 @@ else:
     ASSIGN_NODES = (ast.Assign)
 
 
+def filter_whitespace(code):
+    # type: (unicode) -> unicode
+    return code.replace('\f', ' ')  # replace FF (form feed) with whitespace
+
+
 def get_assign_targets(node):
     # type: (ast.AST) -> List[ast.expr]
     """Get list of targets from Assign and AnnAssign node."""
@@ -467,7 +472,7 @@ class Parser(object):
 
     def __init__(self, code, encoding='utf-8'):
         # type: (unicode, unicode) -> None
-        self.code = code
+        self.code = filter_whitespace(code)
         self.encoding = encoding
         self.comments = {}          # type: Dict[Tuple[unicode, unicode], unicode]
         self.deforders = {}         # type: Dict[unicode, int]

sphinx/themes/basic/search.html

@@ -9,10 +9,10 @@
 #}
 {%- extends "layout.html" %}
 {% set title = _('Search') %}
-{%- macro script() %}
+{%- block scripts %}
     {{ super() }}
     <script type="text/javascript" src="{{ pathto('_static/searchtools.js', 1) }}"></script>
-{%- endmacro %}
+{%- endblock %}
 {% block extrahead %}
   <script type="text/javascript">
     jQuery(function() { Search.loadIndex("{{ pathto('searchindex.js', 1) }}"); });

sphinx/themes/bizstyle/layout.html

@@ -9,10 +9,10 @@
 #}
 {% extends "basic/layout.html" %}
 
-{%- macro script() %}
+{%- block scripts %}
     {{ super() }}
     <script type="text/javascript" src="{{ pathto('_static/bizstyle.js', 1) }}"></script>
-{%- endmacro %}
+{%- endblock %}
 
 {# put the sidebar before the body #}
 {% block sidebar1 %}{{ sidebar() }}{% endblock %}

sphinx/themes/classic/layout.html

@@ -10,8 +10,8 @@
 {%- extends "basic/layout.html" %}
 
 {% if theme_collapsiblesidebar|tobool %}
-{%- macro script() %}
+{%- block scripts %}
     {{ super() }}
     <script type="text/javascript" src="{{ pathto('_static/sidebar.js', 1) }}"></script>
-{%- endmacro %}
+{%- endblock %}
 {% endif %}

sphinx/themes/scrolls/layout.html

@@ -13,10 +13,10 @@
     {{ super() }}
     <link rel="stylesheet" href="_static/print.css" type="text/css" />
 {%- endblock %}
-{%- macro script() %}
+{%- block scripts %}
     {{ super() }}
     <script type="text/javascript" src="{{ pathto('_static/theme_extras.js', 1) }}"></script>
-{%- endmacro %}
+{%- endblock %}
 {# do not display relbars #}
 {% block relbar1 %}{% endblock %}
 {% block relbar2 %}{% endblock %}

sphinx/util/console.py

@@ -87,9 +87,21 @@ def coloron():
     codes.update(_orig_codes)
 
 
-def colorize(name, text):
-    # type: (str, unicode) -> unicode
-    return codes.get(name, '') + text + codes.get('reset', '')
+def colorize(name, text, input_mode=False):
+    # type: (str, unicode, bool) -> unicode
+    def escseq(name):
+        # Wrap escape sequence with ``\1`` and ``\2`` to let readline know
+        # it is non-printable characters
+        # ref: https://tiswww.case.edu/php/chet/readline/readline.html
+        #
+        # Note: This hack does not work well in Windows (see #5059)
+        escape = codes.get(name, '')
+        if input_mode and escape and sys.platform != 'win32':
+            return '\1' + escape + '\2'
+        else:
+            return escape
+
+    return escseq(name) + text + escseq('reset')
 
 
 def strip_colors(s):

sphinx/util/inspect.py

@@ -176,8 +176,8 @@ def isstaticmethod(obj, cls=None, name=None):
     elif cls and name:
         # trace __mro__ if the method is defined in parent class
         #
-        # .. note:: This only works with new style classes.
-        for basecls in getattr(cls, '__mro__', []):
+        # .. note:: This only works well with new style classes.
+        for basecls in getattr(cls, '__mro__', [cls]):
             meth = basecls.__dict__.get(name)
             if meth:
                 if isinstance(meth, staticmethod):

tests/test_ext_math.py

@@ -89,6 +89,18 @@ def test_imgmath_svg(app, status, warning):
     assert re.search(html, content, re.S)
 
 
+@pytest.mark.sphinx('html', testroot='ext-math',
+                    confoverrides={'extensions': ['sphinx.ext.mathjax'],
+                                   'mathjax_options': {'integrity': 'sha384-0123456789'}})
+def test_mathjax_options(app, status, warning):
+    app.builder.build_all()
+
+    content = (app.outdir / 'index.html').text()
+    assert ('<script async="async" integrity="sha384-0123456789" type="text/javascript" '
+            'src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?'
+            'config=TeX-AMS-MML_HTMLorMML"></script>' in content)
+
+
 @pytest.mark.sphinx('html', testroot='ext-math',
                     confoverrides={'extensions': ['sphinx.ext.mathjax']})
 def test_mathjax_align(app, status, warning):

tests/test_pycode_parser.py

@@ -315,3 +315,12 @@ def test_decorators():
                                   'func3': ('def', 7, 9),
                                   'Foo': ('class', 11, 15),
                                   'Foo.method': ('def', 13, 15)}
+
+
+def test_formfeed_char():
+    source = ('class Foo:\n'
+              '\f\n'
+              '    attr = 1234  #: comment\n')
+    parser = Parser(source)
+    parser.parse()
+    assert parser.comments == {('Foo', 'attr'): 'comment'}

tests/test_util_inspect.py

@@ -380,3 +380,26 @@ def test_dict_customtype():
     description = inspect.object_description(dictionary)
     # Type is unsortable, just check that it does not crash
     assert "<CustomType(2)>: 2" in description
+
+
+def test_isstaticmethod():
+    class Foo():
+        @staticmethod
+        def method1():
+            pass
+
+        def method2(self):
+            pass
+
+    class Bar(Foo):
+        pass
+
+    assert inspect.isstaticmethod(Foo.method1, Foo, 'method1') is True
+    assert inspect.isstaticmethod(Foo.method2, Foo, 'method2') is False
+
+    if sys.version_info < (3, 0):
+        assert inspect.isstaticmethod(Bar.method1, Bar, 'method1') is False
+        assert inspect.isstaticmethod(Bar.method2, Bar, 'method2') is False
+    else:
+        assert inspect.isstaticmethod(Bar.method1, Bar, 'method1') is True
+        assert inspect.isstaticmethod(Bar.method2, Bar, 'method2') is False