Merge branch '1.8'

CHANGES

@@ -63,12 +63,16 @@ Dependencies
 Incompatible changes
 --------------------
 
+* #5497: Do not include MathJax.js and jsmath.js unless it is really needed
+
 Deprecated
 ----------
 
 Features added
 --------------
 
+* #5471: Show appropriate deprecation warnings
+
 Bugs fixed
 ----------
 
@@ -80,6 +84,10 @@ Bugs fixed
 * #5495: csv-table directive with file option in included file is broken (refs:
   #4821)
 * #5498: autodoc: unable to find type hints for a ``functools.partial``
+* #5480: autodoc: unable to find type hints for unresolvable Forward references
+* #5419: incompatible math_block node has been generated
+* #5548: Fix ensuredir() in case of pre-existing file
+* #5549: graphviz Correctly deal with non-existing static dir
 
 Testing
 --------
@@ -206,7 +214,7 @@ Deprecated
 * :confval:`autodoc_default_flags` is deprecated
 * quickstart: ``--epub`` option becomes default, so it is deprecated
 * Drop function based directive support.  For now, Sphinx only supports class
-  based directives.
+  based directives (see :class:`~Directive`)
 * ``sphinx.util.docutils.directive_helper()`` is deprecated
 * ``sphinx.cmdline`` is deprecated
 * ``sphinx.make_mode`` is deprecated

setup.cfg

@@ -55,6 +55,7 @@ strict_optional = False
 
 [tool:pytest]
 filterwarnings =
+    all
     ignore::DeprecationWarning:docutils.io
 
 [coverage:run]

sphinx/__init__.py

@@ -29,8 +29,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

@@ -403,7 +403,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
@@ -595,7 +595,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
@@ -727,7 +727,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_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):
@@ -999,7 +999,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/html.py

@@ -121,22 +121,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
@@ -1104,7 +1104,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)
             logger.warning(*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

@@ -161,7 +161,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]
@@ -199,13 +199,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

@@ -39,25 +39,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

@@ -61,7 +61,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/math.py

@@ -44,6 +44,7 @@ class MathDomain(Domain):
 
     initial_data = {
         'objects': {},  # labelid -> (docname, eqno)
+        'has_equations': {},  # docname -> bool
     }  # type: Dict[unicode, Dict[unicode, Tuple[unicode, int]]]
     dangling_warnings = {
         'eq': 'equation not found: %(target)s',
@@ -56,18 +57,30 @@ class MathDomain(Domain):
         'numref': MathReferenceRole(),
     }
 
+    def process_doc(self, env, docname, document):
+        # type: (BuildEnvironment, unicode, nodes.Node) -> None
+        def math_node(node):
+            return isinstance(node, (nodes.math, nodes.math_block))
+
+        self.data['has_equations'][docname] = any(document.traverse(math_node))
+
     def clear_doc(self, docname):
         # type: (unicode) -> None
         for equation_id, (doc, eqno) in list(self.data['objects'].items()):
             if doc == docname:
                 del self.data['objects'][equation_id]
 
+        self.data['has_equations'].pop(docname, None)
+
     def merge_domaindata(self, docnames, otherdata):
         # type: (Iterable[unicode], Dict) -> None
         for labelid, (doc, eqno) in otherdata['objects'].items():
             if doc in docnames:
                 self.data['objects'][labelid] = (doc, eqno)
 
+        for docname in docnames:
+            self.data['has_equations'][docname] = otherdata['has_equations'][docname]
+
     def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
         # type: (BuildEnvironment, unicode, Builder, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node  # NOQA
         assert typ in ('eq', 'numref')
@@ -122,6 +135,10 @@ def get_next_equation_number(self, docname):
         targets = [eq for eq in self.data['objects'].values() if eq[0] == docname]
         return len(targets) + 1
 
+    def has_equations(self):
+        # type: () -> bool
+        return any(self.data['has_equations'].values())
+
 
 def setup(app):
     # type: (Sphinx) -> Dict[unicode, Any]
@@ -130,7 +147,7 @@ def setup(app):
 
     return {
         'version': 'builtin',
-        'env_version': 1,
+        'env_version': 2,
         'parallel_read_safe': True,
         'parallel_write_safe': True,
     }

sphinx/domains/std.py

@@ -952,7 +952,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):