Fix sphinx-doc#5471: Show appropriate warning for deprecated APIs

CHANGES

@@ -13,6 +13,8 @@ Deprecated
 Features added
 --------------
 
+* #5471: Show appropriate deprecation warnings
+
 Bugs fixed
 ----------
 

sphinx/__init__.py

@@ -31,8 +31,7 @@
 # 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')
+    warnings.filterwarnings('default', category=RemovedInNextVersionWarning)
 # docutils.io using mode='rU' for open
 warnings.filterwarnings('ignore', "'U' mode is deprecated",
                         DeprecationWarning, module='docutils.io')

sphinx/addnodes.py

@@ -205,7 +205,7 @@ def __getitem__(self, key):
         if key == 'latex' and 'latex' not in self.attributes:
             warnings.warn("math node for Sphinx was replaced by docutils'. "
                           "Therefore please use ``node.astext()`` to get an equation instead.",
-                          RemovedInSphinx30Warning)
+                          RemovedInSphinx30Warning, stacklevel=2)
             return self.astext()
         else:
             return nodes.math.__getitem__(self, key)
@@ -224,7 +224,7 @@ def __getitem__(self, key):
         if key == 'latex' and 'latex' not in self.attributes:
             warnings.warn("displaymath node for Sphinx was replaced by docutils'. "
                           "Therefore please use ``node.astext()`` to get an equation instead.",
-                          RemovedInSphinx30Warning)
+                          RemovedInSphinx30Warning, stacklevel=2)
             return self.astext()
         else:
             return nodes.math_block.__getitem__(self, key)

sphinx/application.py

@@ -385,7 +385,7 @@ def warn(self, message, location=None, type=None, subtype=None):
            Use :mod:`sphinx.util.logging` instead.
         """
         warnings.warn('app.warning() is now deprecated. Use sphinx.util.logging instead.',
-                      RemovedInSphinx20Warning)
+                      RemovedInSphinx20Warning, stacklevel=2)
         logger.warning(message, type=type, subtype=subtype, location=location)
 
     def info(self, message='', nonl=False):
@@ -399,7 +399,7 @@ def info(self, message='', nonl=False):
            Use :mod:`sphinx.util.logging` instead.
         """
         warnings.warn('app.info() is now deprecated. Use sphinx.util.logging instead.',
-                      RemovedInSphinx20Warning)
+                      RemovedInSphinx20Warning, stacklevel=2)
         logger.info(message, nonl=nonl)
 
     def verbose(self, message, *args, **kwargs):
@@ -410,7 +410,7 @@ def verbose(self, message, *args, **kwargs):
            Use :mod:`sphinx.util.logging` instead.
         """
         warnings.warn('app.verbose() is now deprecated. Use sphinx.util.logging instead.',
-                      RemovedInSphinx20Warning)
+                      RemovedInSphinx20Warning, stacklevel=2)
         logger.verbose(message, *args, **kwargs)
 
     def debug(self, message, *args, **kwargs):
@@ -421,7 +421,7 @@ def debug(self, message, *args, **kwargs):
            Use :mod:`sphinx.util.logging` instead.
         """
         warnings.warn('app.debug() is now deprecated. Use sphinx.util.logging instead.',
-                      RemovedInSphinx20Warning)
+                      RemovedInSphinx20Warning, stacklevel=2)
         logger.debug(message, *args, **kwargs)
 
     def debug2(self, message, *args, **kwargs):
@@ -432,7 +432,7 @@ def debug2(self, message, *args, **kwargs):
            Use :mod:`sphinx.util.logging` instead.
         """
         warnings.warn('app.debug2() is now deprecated. Use debug() instead.',
-                      RemovedInSphinx20Warning)
+                      RemovedInSphinx20Warning, stacklevel=2)
         logger.debug(message, *args, **kwargs)
 
     # ---- general extensibility interface -------------------------------------
@@ -470,7 +470,7 @@ def import_object(self, objname, source=None):
         """
         warnings.warn('app.import_object() is deprecated. '
                       'Use sphinx.util.add_object_type() instead.',
-                      RemovedInSphinx30Warning)
+                      RemovedInSphinx30Warning, stacklevel=2)
         return import_object(objname, source=None)
 
     # event interface
@@ -663,7 +663,7 @@ def enumerable_nodes(self):
         # type: () -> Dict[nodes.Node, Tuple[unicode, TitleGetter]]
         warnings.warn('app.enumerable_nodes() is deprecated. '
                       'Use app.get_domain("std").enumerable_nodes instead.',
-                      RemovedInSphinx30Warning)
+                      RemovedInSphinx30Warning, stacklevel=2)
         return self.registry.enumerable_nodes
 
     def add_directive(self, name, obj, content=None, arguments=None, override=False, **options):  # NOQA
@@ -801,7 +801,7 @@ def override_domain(self, domain):
         """
         warnings.warn('app.override_domain() is deprecated. '
                       'Use app.add_domain() with override option instead.',
-                      RemovedInSphinx30Warning)
+                      RemovedInSphinx30Warning, stacklevel=2)
         self.registry.add_domain(domain, override=True)
 
     def add_directive_to_domain(self, domain, name, obj, has_content=None, argument_spec=None,
@@ -924,7 +924,7 @@ def add_description_unit(self, directivename, rolename, indextemplate='',
         """
         warnings.warn('app.add_description_unit() is now deprecated. '
                       'Use app.add_object_type() instead.',
-                      RemovedInSphinx20Warning)
+                      RemovedInSphinx20Warning, stacklevel=2)
         self.add_object_type(directivename, rolename, indextemplate, parse_node,
                              ref_nodeclass, objname, doc_field_types)
 
@@ -1013,7 +1013,7 @@ def add_javascript(self, filename, **kwargs):
         """An alias of :meth:`add_js_file`."""
         warnings.warn('The app.add_javascript() is deprecated. '
                       'Please use app.add_js_file() instead.',
-                      RemovedInSphinx40Warning)
+                      RemovedInSphinx40Warning, stacklevel=2)
         self.add_js_file(filename, **kwargs)
 
     def add_js_file(self, filename, **kwargs):
@@ -1088,7 +1088,7 @@ def add_stylesheet(self, filename, alternate=False, title=None):
         """An alias of :meth:`add_css_file`."""
         warnings.warn('The app.add_stylesheet() is deprecated. '
                       'Please use app.add_css_file() instead.',
-                      RemovedInSphinx40Warning)
+                      RemovedInSphinx40Warning, stacklevel=2)
 
         attributes = {}  # type: Dict[unicode, unicode]
         if alternate:

sphinx/builders/__init__.py

@@ -150,7 +150,7 @@ def translator_class(self):
             warnings.warn('builder.translator_class() is now deprecated. '
                           'Please use builder.create_translator() and '
                           'builder.default_translator_class instead.',
-                          RemovedInSphinx20Warning)
+                          RemovedInSphinx20Warning, stacklevel=2)
             return None
         return self.create_translator
 

sphinx/builders/html.py

@@ -109,7 +109,7 @@ def insert(self, index, obj):
         # type: (int, Union[unicode, Stylesheet]) -> None
         warnings.warn('builder.css_files is deprecated. '
                       'Please use app.add_stylesheet() instead.',
-                      RemovedInSphinx20Warning)
+                      RemovedInSphinx20Warning, stacklevel=2)
         if isinstance(obj, Stylesheet):
             super(CSSContainer, self).insert(index, obj)
         else:
@@ -119,15 +119,15 @@ def extend(self, other):  # type: ignore
         # type: (List[Union[unicode, Stylesheet]]) -> None
         warnings.warn('builder.css_files is deprecated. '
                       'Please use app.add_stylesheet() instead.',
-                      RemovedInSphinx20Warning)
+                      RemovedInSphinx20Warning, stacklevel=2)
         for item in other:
             self.append(item)
 
     def __iadd__(self, other):  # type: ignore
         # type: (List[Union[unicode, Stylesheet]]) -> CSSContainer
         warnings.warn('builder.css_files is deprecated. '
                       'Please use app.add_stylesheet() instead.',
-                      RemovedInSphinx20Warning)
+                      RemovedInSphinx20Warning, stacklevel=2)
         for item in other:
             self.append(item)
         return self
@@ -169,22 +169,22 @@ def insert(self, index, obj):
         # type: (int, unicode) -> None
         warnings.warn('builder.script_files is deprecated. '
                       'Please use app.add_js_file() instead.',
-                      RemovedInSphinx30Warning)
+                      RemovedInSphinx30Warning, stacklevel=2)
         super(JSContainer, self).insert(index, obj)
 
     def extend(self, other):  # type: ignore
         # type: (List[unicode]) -> None
         warnings.warn('builder.script_files is deprecated. '
                       'Please use app.add_js_file() instead.',
-                      RemovedInSphinx30Warning)
+                      RemovedInSphinx30Warning, stacklevel=2)
         for item in other:
             self.append(item)
 
     def __iadd__(self, other):  # type: ignore
         # type: (List[unicode]) -> JSContainer
         warnings.warn('builder.script_files is deprecated. '
                       'Please use app.add_js_file() instead.',
-                      RemovedInSphinx30Warning)
+                      RemovedInSphinx30Warning, stacklevel=2)
         for item in other:
             self.append(item)
         return self
@@ -1092,7 +1092,7 @@ def has_wildcard(pattern):
             warnings.warn('Now html_sidebars only allows list of sidebar '
                           'templates as a value. Support for a string value '
                           'will be removed at Sphinx-2.0.',
-                          RemovedInSphinx20Warning)
+                          RemovedInSphinx20Warning, stacklevel=2)
 
         ctx['sidebars'] = sidebars
         ctx['customsidebar'] = customsidebar
@@ -1161,7 +1161,7 @@ def warn(*args, **kwargs):
             """Simple warn() wrapper for themes."""
             warnings.warn('The template function warn() was deprecated. '
                           'Use warning() instead.',
-                          RemovedInSphinx30Warning)
+                          RemovedInSphinx30Warning, stacklevel=2)
             self.warn(*args, **kwargs)
             return ''  # return empty string
         ctx['warn'] = warn

sphinx/cmdline.py

@@ -27,26 +27,26 @@
 def handle_exception(app, args, exception, stderr=sys.stderr):
     # type: (Sphinx, Any, Union[Exception, KeyboardInterrupt], IO) -> None
     warnings.warn('sphinx.cmdline module is deprecated. Use sphinx.cmd.build instead.',
-                  RemovedInSphinx30Warning)
+                  RemovedInSphinx30Warning, stacklevel=2)
     build.handle_exception(app, args, exception, stderr)
 
 
 def jobs_argument(value):
     # type: (str) -> int
     warnings.warn('sphinx.cmdline module is deprecated. Use sphinx.cmd.build instead.',
-                  RemovedInSphinx30Warning)
+                  RemovedInSphinx30Warning, stacklevel=2)
     return build.jobs_argument(value)
 
 
 def get_parser():
     # type: () -> argparse.ArgumentParser
     warnings.warn('sphinx.cmdline module is deprecated. Use sphinx.cmd.build instead.',
-                  RemovedInSphinx30Warning)
+                  RemovedInSphinx30Warning, stacklevel=2)
     return build.get_parser()
 
 
 def main(argv=sys.argv[1:]):  # type: ignore
     # type: (List[unicode]) -> int
     warnings.warn('sphinx.cmdline module is deprecated. Use sphinx.cmd.build instead.',
-                  RemovedInSphinx30Warning)
+                  RemovedInSphinx30Warning, stacklevel=2)
     return build.main(argv)

sphinx/config.py

@@ -168,7 +168,7 @@ def __init__(self, *args):
             # old style arguments: (dirname, filename, overrides, tags)
             warnings.warn('The argument of Config() class has been changed. '
                           'Use Config.read() to read configuration from conf.py.',
-                          RemovedInSphinx30Warning)
+                          RemovedInSphinx30Warning, stacklevel=2)
             dirname, filename, overrides, tags = args
             if dirname is None:
                 config = {}  # type: Dict[unicode, Any]
@@ -206,13 +206,13 @@ def read(cls, confdir, overrides=None, tags=None):
     def check_types(self):
         # type: () -> None
         warnings.warn('Config.check_types() is deprecated. Use check_confval_types() instead.',
-                      RemovedInSphinx30Warning)
+                      RemovedInSphinx30Warning, stacklevel=2)
         check_confval_types(None, self)
 
     def check_unicode(self):
         # type: () -> None
         warnings.warn('Config.check_unicode() is deprecated. Use check_unicode() instead.',
-                      RemovedInSphinx30Warning)
+                      RemovedInSphinx30Warning, stacklevel=2)
         check_unicode(self)
 
     def convert_overrides(self, name, value):

sphinx/deprecation.py

@@ -43,25 +43,25 @@ def __init__(self, data, message, warning):
 
     def __setitem__(self, key, value):
         # type: (unicode, Any) -> None
-        warnings.warn(self.message, self.warning)
+        warnings.warn(self.message, self.warning, stacklevel=2)
         super(DeprecatedDict, self).__setitem__(key, value)
 
     def setdefault(self, key, default=None):
         # type: (unicode, Any) -> None
-        warnings.warn(self.message, self.warning)
+        warnings.warn(self.message, self.warning, stacklevel=2)
         return super(DeprecatedDict, self).setdefault(key, default)
 
     def __getitem__(self, key):
         # type: (unicode) -> None
-        warnings.warn(self.message, self.warning)
+        warnings.warn(self.message, self.warning, stacklevel=2)
         return super(DeprecatedDict, self).__getitem__(key)
 
     def get(self, key, default=None):
         # type: (unicode, Any) -> None
-        warnings.warn(self.message, self.warning)
+        warnings.warn(self.message, self.warning, stacklevel=2)
         return super(DeprecatedDict, self).get(key, default)
 
     def update(self, other=None):  # type: ignore
         # type: (Dict) -> None
-        warnings.warn(self.message, self.warning)
+        warnings.warn(self.message, self.warning, stacklevel=2)
         super(DeprecatedDict, self).update(other)

sphinx/directives/code.py

@@ -62,7 +62,7 @@ def run(self):
         # type: () -> List[nodes.Node]
         warnings.warn('highlightlang directive is deprecated. '
                       'Please use highlight directive instead.',
-                      RemovedInSphinx40Warning)
+                      RemovedInSphinx40Warning, stacklevel=2)
         return Highlight.run(self)
 
 

sphinx/domains/std.py

@@ -953,7 +953,7 @@ def get_figtype(self, node):
         """
         warnings.warn('StandardDomain.get_figtype() is deprecated. '
                       'Please use get_enumerable_node_type() instead.',
-                      RemovedInSphinx30Warning)
+                      RemovedInSphinx30Warning, stacklevel=2)
         return self.get_enumerable_node_type(node)
 
     def get_fignumber(self, env, builder, figtype, docname, target_node):