Inprovement of warnings mechanism. Now support disabling emit warnings and add documentation.

.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

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.
+* Emit warnings that will be deprecated in Sphinx 1.6 by default.
-  There is no way to hide the warnings.
+  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
 --------------

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)

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:

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:
 

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
 

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 = {}

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

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