diff --git a/.travis.yml b/.travis.yml index 5f035b73b..8cef03f44 100644 --- a/.travis.yml +++ b/.travis.yml @@ -13,6 +13,7 @@ env: global: - TEST='-v --with-timer --timer-top-n 25' - PYTHONFAULTHANDLER=x + - PYTHONWARNINGS=all matrix: - DOCUTILS=0.11 - DOCUTILS=0.12 diff --git a/CHANGES b/CHANGES index 8aaf0a274..b27b55db1 100644 --- a/CHANGES +++ b/CHANGES @@ -5,8 +5,24 @@ Incompatible changes -------------------- * #2986: ``themes/basic/defindex.html`` is now deprecated -* Emit several warnings that will be deprecated in Sphinx 1.6. - There is no way to hide the warnings. +* Emit warnings that will be deprecated in Sphinx 1.6 by default. + Users can change the behavior by setting the environment variable + PYTHONWARNINGS. Please refer :ref:`when-deprecation-warnings-are-displayed`. + +Deprecated +---------- + +These features are removed in Sphinx-1.6: + +* LDML format support in i18n feature +* ``sphinx.addnodes.termsep`` +* Some functions and classes in ``sphinx.util.pycompat``: + ``zip_longest``, ``product``, ``all``, ``any``, ``next``, ``open``, + ``class_types``, ``base_exception``, ``relpath``, ``StringIO``, ``BytesIO``. + Please use the standard library version instead; + +If any deprecation warning like ``RemovedInSphinxXXXWarning`` are displayed, +please refer :ref:`when-deprecation-warnings-are-displayed`. Features added -------------- diff --git a/doc/devguide.rst b/doc/devguide.rst index b621f622a..f29646550 100644 --- a/doc/devguide.rst +++ b/doc/devguide.rst @@ -114,6 +114,11 @@ These are the basic steps needed to start developing on Sphinx. pip install -r test-reqs.txt make test + * Again, it's useful to turn on deprecation warnings on so they're shown in + the test output:: + + PYTHONWARNINGS=all make test + * Build the documentation and check the output for different builders:: cd doc @@ -272,3 +277,55 @@ Debugging Tips $ npm install $ node_modules/.bin/grunt build # -> dest/*.global.js + +Deprecating a feature +--------------------- + +There are a couple reasons that code in Sphinx might be deprecated: + +* If a feature has been improved or modified in a backwards-incompatible way, + the old feature or behavior will be deprecated. + +* Sometimes Sphinx will include a backport of a Python library that's not + included in a version of Python that Sphinx currently supports. When Sphinx + no longer needs to support the older version of Python that doesn't include + the library, the library will be deprecated in Sphinx. + +As the :ref:`deprecation-policy` describes, +the first release of Sphinx that deprecates a feature (``A.B``) should raise a +``RemovedInSphinxXXWarning`` (where XX is the Sphinx version where the feature +will be removed) when the deprecated feature is invoked. Assuming we have good +test coverage, these warnings are converted to errors when running the test +suite with warnings enabled: ``python -Wall tests/run.py``. Thus, when adding +a ``RemovedInSphinxXXWarning`` you need to eliminate or silence any warnings +generated when running the tests. + +.. _deprecation-policy: + +Deprecation policy +------------------ + +A feature release may deprecate certain features from previous releases. If a +feature is deprecated in feature release 1.A, it will continue to work in all +1.A.x versions (for all versions of x) but raise warnings. Deprecated features +will be removed in the first 1.B release, or 1.B.1 for features deprecated in +the last 1.A.x feature release to ensure deprecations are done over at least 2 +feature releases. + +So, for example, if we decided to start the deprecation of a function in +Sphinx 1.4: + +* Sphinx 1.4.x will contain a backwards-compatible replica of the function + which will raise a ``RemovedInSphinx16Warning``. + +* Sphinx 1.5 (the version that follows 1.4) will still contain the + backwards-compatible replica. + +* Sphinx 1.6 will remove the feature outright. + +The warnings are displayed by default. You can turn off display of these +warnings with: + +* ``PYTHONWARNINGS= make html`` (Linux/Mac) +* ``export PYTHONWARNINGS=`` and do ``make html`` (Linux/Mac) +* ``set PYTHONWARNINGS=`` and do ``make html`` (Windows) diff --git a/doc/glossary.rst b/doc/glossary.rst index 3ef1623db..a92e52b98 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -73,6 +73,11 @@ Glossary directive" (e.g. :rst:dir:`function` or :rst:dir:`object`) creates such a block; and most objects can be cross-referenced to. + RemoveInSphinxXXXWarning + The feature which is warned will be removed in Sphinx-XXX version. + It usually caused from Sphinx extensions which is using deprecated. + See also :ref:`when-deprecation-warnings-are-displayed`. + role A reStructuredText markup element that allows marking a piece of text. Like directives, roles are extensible. The basic syntax looks like this: diff --git a/doc/invocation.rst b/doc/invocation.rst index 4b4593014..a16ab2128 100644 --- a/doc/invocation.rst +++ b/doc/invocation.rst @@ -410,6 +410,23 @@ variables to customize behavior: Additional options for :program:`sphinx-build`. +.. _when-deprecation-warnings-are-displayed: + +Deprecation Warnings +-------------------- + +If any deprecation warning like ``RemovedInSphinxXXXWarning`` are displayed +when building a user's document, some Sphinx extension is using deprecated +features. In that case, please report it to author of the extension. + +To disable the deprecation warnings, please set ``PYTHONWARNINGS=`` environment +variable to your environment. For example: + +* ``PYTHONWARNINGS= make html`` (Linux/Mac) +* ``export PYTHONWARNINGS=`` and do ``make html`` (Linux/Mac) +* ``set PYTHONWARNINGS=`` and do ``make html`` (Windows) +* modify your Makefile/make.bat and set the environment variable + .. _invocation-apidoc: diff --git a/sphinx/__init__.py b/sphinx/__init__.py index 415a85421..84265e51e 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -12,9 +12,24 @@ # Keep this file executable as-is in Python 3! # (Otherwise getting the version out of it from setup.py is impossible.) +from __future__ import absolute_import + +import os import sys +import warnings from os import path +from .deprecation import RemovedInNextVersionWarning + +# by default, all DeprecationWarning under sphinx package will be emit. +# Users can avoid this by using environment variable: PYTHONWARNINGS= +if 'PYTHONWARNINGS' not in os.environ: + warnings.filterwarnings('default', + category=RemovedInNextVersionWarning, module='sphinx') +# docutils.io using mode='rU' for open +warnings.filterwarnings('ignore', "'U' mode is deprecated", + DeprecationWarning, module='docutils.io') + __version__ = '1.5b2' __released__ = '1.5b2' # used when Sphinx builds its own docs diff --git a/sphinx/application.py b/sphinx/application.py index e1e0af512..cee780c9c 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -17,7 +17,6 @@ import sys import types import posixpath import traceback -import warnings from os import path from collections import deque @@ -33,7 +32,6 @@ from sphinx.roles import XRefRole from sphinx.config import Config from sphinx.errors import SphinxError, SphinxWarning, ExtensionError, \ VersionRequirementError, ConfigError -from sphinx.deprecation import RemovedInSphinx16Warning from sphinx.domains import ObjType from sphinx.domains.std import GenericObject, Target, StandardDomain from sphinx.environment import BuildEnvironment @@ -108,8 +106,6 @@ class Sphinx(object): confoverrides=None, status=sys.stdout, warning=sys.stderr, freshenv=False, warningiserror=False, tags=None, verbosity=0, parallel=0): - warnings.filterwarnings('default', category=RemovedInSphinx16Warning, - module='sphinx') self.verbosity = verbosity self.next_listener_id = 0 self._extensions = {} diff --git a/sphinx/util/pycompat.py b/sphinx/util/pycompat.py index d268ef6ae..69a5e07cf 100644 --- a/sphinx/util/pycompat.py +++ b/sphinx/util/pycompat.py @@ -106,7 +106,8 @@ def execfile_(filepath, _globals, open=open): from sphinx.util.osutil import fs_encoding # get config source -- 'b' is a no-op under 2.x, while 'U' is # ignored under 3.x (but 3.x compile() accepts \r\n newlines) - with open(filepath, 'rbU') as f: + mode = 'rb' if PY3 else 'rbU' + with open(filepath, mode) as f: source = f.read() # py26 accept only LF eol instead of CRLF diff --git a/tox.ini b/tox.ini index ca3cac99b..1ccaa583f 100644 --- a/tox.ini +++ b/tox.ini @@ -14,7 +14,7 @@ deps= setenv = SPHINX_TEST_TEMPDIR = {envdir}/testbuild commands= - {envpython} tests/run.py -I py35 -m '^[tT]est' {posargs} + {envpython} -Wall tests/run.py -I py35 -m '^[tT]est' {posargs} sphinx-build -q -W -b html -d {envtmpdir}/doctrees doc {envtmpdir}/html [testenv:pypy] @@ -48,5 +48,5 @@ deps= [testenv:py35] commands= - {envpython} tests/run.py -m '^[tT]est' {posargs} + {envpython} -Wall tests/run.py -m '^[tT]est' {posargs} sphinx-build -q -W -b html -d {envtmpdir}/doctrees doc {envtmpdir}/html