diff --git a/CHANGES b/CHANGES index 100bab1a5..aa15a5b3d 100644 --- a/CHANGES +++ b/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 +`_ Bugs fixed ---------- diff --git a/LICENSE b/LICENSE index 4354c0790..2e4c26cd8 100644 --- a/LICENSE +++ b/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: diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index e04aa15c0..6ce3fd899 100644 --- a/doc/extdev/index.rst +++ b/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 `_ + + * - ``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. diff --git a/setup.cfg b/setup.cfg index c993e75ec..ac4dafdbc 100644 --- a/setup.cfg +++ b/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 diff --git a/setup.py b/setup.py index 9e1fd883f..305ca2ab0 100644 --- a/setup.py +++ b/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__, diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index b4f009de5..c7f38377d 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/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 diff --git a/sphinx/util/docutils.py b/sphinx/util/docutils.py index a91cb3068..2af5a1cb7 100644 --- a/sphinx/util/docutils.py +++ b/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) diff --git a/sphinx/util/inspect.py b/sphinx/util/inspect.py index 337d3f76a..ab20787c1 100644 --- a/sphinx/util/inspect.py +++ b/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 diff --git a/tests/test_ext_autosummary.py b/tests/test_ext_autosummary.py index f9e217801..f988195a9 100644 --- a/tests/test_ext_autosummary.py +++ b/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):