Merge branch '1.7'

CHANGES

@@ -73,6 +73,7 @@ Bugs fixed
 ----------
 
 * #4669: sphinx.build_main and sphinx.make_main throw NameError
+* #4685: autosummary emits meaningless warnings
 
 Testing
 --------
@@ -83,12 +84,13 @@ Release 1.7.1 (released Feb 23, 2018)
 Deprecated
 ----------
 
-* #4623: ``sphinx.build_main()`` is deprecated. Use
-  ``sphinx.cmd.build.build_main()`` instead.
+* #4623: ``sphinx.build_main()`` is deprecated.
 * autosummary: The interface of ``sphinx.ext.autosummary.get_documenter()`` has
   been changed (Since 1.7.0)
-* #4664: ``sphinx.ext.intersphinx.debug()`` is deprecated. Use
-  ``sphinx.ext.intersphinx.inspect_main()`` instead.
+* #4664: ``sphinx.ext.intersphinx.debug()`` is deprecated.
+
+For more details, see `deprecation APIs list
+<http://www.sphinx-doc.org/en/master/extdev/index.html#deprecated-apis>`_
 
 Bugs fixed
 ----------

LICENSE

@@ -31,64 +31,6 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 Licenses for incorporated software
 ==================================
 
-The pgen2 package, included in this distribution under the name
-sphinx.pycode.pgen2, is available in the Python 2.6 distribution under
-the PSF license agreement for Python:
-
-----------------------------------------------------------------------
-Copyright © 2001-2008 Python Software Foundation; All Rights Reserved.
-
-PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
---------------------------------------------
-
-1. This LICENSE AGREEMENT is between the Python Software Foundation
-   ("PSF"), and the Individual or Organization ("Licensee") accessing
-   and otherwise using Python 2.6 software in source or binary form
-   and its associated documentation.
-
-2. Subject to the terms and conditions of this License Agreement, PSF
-   hereby grants Licensee a nonexclusive, royalty-free, world-wide
-   license to reproduce, analyze, test, perform and/or display
-   publicly, prepare derivative works, distribute, and otherwise use
-   Python 2.6 alone or in any derivative version, provided, however,
-   that PSF's License Agreement and PSF's notice of copyright, i.e.,
-   "Copyright © 2001-2008 Python Software Foundation; All Rights
-   Reserved" are retained in Python 2.6 alone or in any derivative
-   version prepared by Licensee.
-
-3. In the event Licensee prepares a derivative work that is based on
-   or incorporates Python 2.6 or any part thereof, and wants to make
-   the derivative work available to others as provided herein, then
-   Licensee hereby agrees to include in any such work a brief summary
-   of the changes made to Python 2.6.
-
-4. PSF is making Python 2.6 available to Licensee on an "AS IS" basis.
-   PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.  BY
-   WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY
-   REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY
-   PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.6 WILL NOT INFRINGE
-   ANY THIRD PARTY RIGHTS.
-
-5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
-   2.6 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS
-   AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON
-   2.6, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY
-   THEREOF.
-
-6. This License Agreement will automatically terminate upon a material
-   breach of its terms and conditions.
-
-7. Nothing in this License Agreement shall be deemed to create any
-   relationship of agency, partnership, or joint venture between PSF
-   and Licensee.  This License Agreement does not grant permission to
-   use PSF trademarks or trade name in a trademark sense to endorse or
-   promote products or services of Licensee, or any third party.
-
-8. By copying, installing or otherwise using Python 2.6, Licensee
-   agrees to be bound by the terms and conditions of this License
-   Agreement.
-----------------------------------------------------------------------
-
 The included smartypants module, included as sphinx.util.smartypants,
 is available under the following license:
 

doc/extdev/index.rst

@@ -94,3 +94,129 @@ APIs used for writing extensions
    nodes
    logging
    i18n
+
+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
+major versions (for more details, please see :ref:`deprecation-policy`).
+
+The following is a list of deprecated interface.
+
+.. list-table:: deprecated APIs
+   :header-rows: 1
+
+   * - Target
+     - Deprecated
+     - (will be) Removed
+     - Alternatives
+
+   * - ``sphinx.build_main()``
+     - 1.7
+     - 2.0
+     - ``sphinx.cmd.build.build_main()``
+
+   * - ``sphinx.ext.intersphinx.debug()``
+     - 1.7
+     - 2.0
+     - ``sphinx.ext.intersphinx.inspect_main()``
+
+   * - ``sphinx.ext.autodoc.format_annotation()``
+     - 1.7
+     - 2.0
+     - ``sphinx.util.inspect.Signature``
+
+   * - ``sphinx.ext.autodoc.formatargspec()``
+     - 1.7
+     - 2.0
+     - ``sphinx.util.inspect.Signature``
+
+   * - ``sphinx.ext.autodoc.AutodocReporter``
+     - 1.7
+     - 2.0
+     - ``sphinx.util.docutils.switch_source_input()``
+
+   * - ``sphinx.ext.autodoc.add_documenter()``
+     - 1.7
+     - 2.0
+     - :meth:`~sphinx.application.Sphinx.add_autodocumenter()`
+
+   * - ``sphinx.ext.autodoc.AutoDirective._register``
+     - 1.7
+     - 2.0
+     - :meth:`~sphinx.application.Sphinx.add_autodocumenter()`
+
+   * - ``AutoDirective._special_attrgetters``
+     - 1.7
+     - 2.0
+     - :meth:`~sphinx.application.Sphinx.add_autodoc_attrgetter()`
+
+   * - ``Sphinx.warn()``, ``Sphinx.info()``
+     - 1.6
+     - 2.0
+     - :ref:`logging-api`
+
+   * - ``BuildEnvironment.set_warnfunc()``
+     - 1.6
+     - 2.0
+     - :ref:`logging-api`
+
+   * - ``BuildEnvironment.note_toctree()``
+     - 1.6
+     - 2.0
+     - ``Toctree.note()`` (in ``sphinx.environment.adapters.toctree``)
+
+   * - ``BuildEnvironment.get_toc_for()``
+     - 1.6
+     - 2.0
+     - ``Toctree.get_toc_for()`` (in ``sphinx.environment.adapters.toctree``)
+
+   * - ``BuildEnvironment.get_toctree_for()``
+     - 1.6
+     - 2.0
+     - ``Toctree.get_toctree_for()`` (in ``sphinx.environment.adapters.toctree``)
+
+   * - ``BuildEnvironment.create_index()``
+     - 1.6
+     - 2.0
+     - ``IndexEntries.create_index()`` (in ``sphinx.environment.adapters.indexentries``)
+
+   * - ``sphinx.websupport``
+     - 1.6
+     - 2.0
+     - `sphinxcontrib-websupport <https://pypi.python.org/pypi/sphinxcontrib-websupport>`_
+
+   * - ``StandaloneHTMLBuilder.css_files``
+     - 1.6
+     - 2.0
+     - :meth:`~sphinx.application.Sphinx.add_stylesheet()`
+
+   * - ``Sphinx.status_iterator()``
+     - 1.6
+     - 1.7
+     - ``sphinx.util.status_iterator()``
+
+   * - ``Sphinx.old_status_iterator()``
+     - 1.6
+     - 1.7
+     - ``sphinx.util.old_status_iterator()``
+
+   * - ``Sphinx._directive_helper()``
+     - 1.6
+     - 1.7
+     - ``sphinx.util.docutils.directive_helper()``
+
+   * - ``sphinx.util.compat.Directive``
+     - 1.6
+     - 1.7
+     - ``docutils.parsers.rst.Directive``
+
+   * - ``sphinx.util.compat.docutils_version``
+     - 1.6
+     - 1.7
+     - ``sphinx.util.docutils.__version_info__``
+
+.. note:: On deprecating on public APIs (internal functions and classes),
+          we also follow the policy as much as possible.

setup.cfg

@@ -32,7 +32,7 @@ directory = sphinx/locale/
 [flake8]
 max-line-length = 95
 ignore = E116,E241,E251,E741,I101
-exclude = .git,.tox,.venv,tests/*,build/*,doc/_build/*,sphinx/search/*,sphinx/pycode/pgen2/*,doc/ext/example*.py
+exclude = .git,.tox,.venv,tests/*,build/*,doc/_build/*,sphinx/search/*,doc/ext/example*.py
 application-import-names = sphinx
 import-order-style = smarkets
 

setup.py

@@ -2,7 +2,6 @@
 import os
 import sys
 from distutils import log
-from distutils.cmd import Command
 from io import StringIO
 
 from setuptools import find_packages, setup
@@ -173,32 +172,6 @@ else:
     cmdclass['compile_catalog'] = compile_catalog_plusjs
 
 
-class CompileGrammarCommand(Command):
-    description = 'Compile python grammar file for pycode'
-    user_options = []
-
-    def initialize_options(self):
-        pass
-
-    def finalize_options(self):
-        pass
-
-    def run(self):
-        from sphinx.pycode.pgen2.driver import compile_grammar
-
-        compile_grammar('sphinx/pycode/Grammar-py2.txt')
-        print('sphinx/pycode/Grammar-py2.txt ... done')
-
-        compile_grammar('sphinx/pycode/Grammar-py3.txt')
-        print('sphinx/pycode/Grammar-py3.txt ... done')
-
-    def sub_commands(self):
-        pass
-
-
-cmdclass['compile_grammar'] = CompileGrammarCommand
-
-
 setup(
     name='Sphinx',
     version=sphinx.__version__,

sphinx/ext/autosummary/__init__.py

@@ -78,7 +78,7 @@ from sphinx.ext.autodoc.directive import DocumenterBridge, Options
 from sphinx.ext.autodoc.importer import import_module
 from sphinx.pycode import ModuleAnalyzer, PycodeError
 from sphinx.util import import_object, rst, logging
-from sphinx.util.docutils import new_document
+from sphinx.util.docutils import NullReporter, new_document
 
 if TYPE_CHECKING:
     from typing import Any, Dict, List, Tuple, Type, Union  # NOQA
@@ -477,6 +477,7 @@ def extract_summary(doc, document):
         while sentences:
             summary += sentences.pop(0) + '.'
             node = new_document('', document.settings)
+            node.reporter = NullReporter()
             state_machine.run([summary], node)
             if not node.traverse(nodes.system_message):
                 # considered as that splitting by period does not break inline markups

sphinx/util/docutils.py

@@ -223,6 +223,14 @@ class LoggingReporter(Reporter):
                           stream, debug, error_handler=error_handler)
 
 
+class NullReporter(Reporter):
+    """A dummy reporter; write nothing."""
+
+    def __init__(self):
+        # type: () -> None
+        Reporter.__init__(self, '', 999, 4)
+
+
 def is_html5_writer_available():
     # type: () -> bool
     return __version_info__ > (0, 13, 0)

sphinx/util/inspect.py

@@ -114,7 +114,7 @@ else:  # 2.7
             func = func.func
         if not inspect.isfunction(func):
             raise TypeError('%r is not a Python function' % func)
-        args, varargs, varkw = inspect.getargs(func.__code__)  # type: ignore
+        args, varargs, varkw = inspect.getargs(func.__code__)
         func_defaults = func.__defaults__
         if func_defaults is None:
             func_defaults = []
@@ -124,13 +124,13 @@ else:  # 2.7
             args = args[parts[0]:]
         if parts[1]:
             for arg in parts[1]:
-                i = args.index(arg) - len(args)
+                i = args.index(arg) - len(args)  # type: ignore
                 del args[i]
                 try:
                     del func_defaults[i]
                 except IndexError:
                     pass
-        return inspect.ArgSpec(args, varargs, varkw, func_defaults)
+        return inspect.ArgSpec(args, varargs, varkw, func_defaults)  # type: ignore
 
 try:
     import enum

tests/test_ext_autosummary.py

@@ -55,7 +55,7 @@ def test_mangle_signature():
         assert res == outp, (u"'%s' -> '%s' != '%s'" % (inp, res, outp))
 
 
-def test_extract_summary():
+def test_extract_summary(capsys):
     from sphinx.util.docutils import new_document
     from mock import Mock
     settings = Mock(language_code='',
@@ -77,6 +77,9 @@ def test_extract_summary():
            'it does not break sentence.']
     assert extract_summary(doc, document) == ' '.join(doc)
 
+    _, err = capsys.readouterr()
+    assert err == ''
+
 
 @pytest.mark.sphinx('dummy', **default_kw)
 def test_get_items_summary(make_app, app_params):