Closes #2157: helper function `warning()` for HTML themes is added

CHANGES

@@ -31,6 +31,7 @@ Deprecated
 * All ``env.update()``, ``env._read_serial()`` and ``env._read_parallel()`` are
   deprecated
 * ``sphinx.locale.l_()`` is deprecated
+* #2157: helper function ``warn()`` for HTML themes is deprecated
 
 For more details, see `deprecation APIs list
 <http://www.sphinx-doc.org/en/master/extdev/index.html#deprecated-apis>`_
@@ -47,6 +48,7 @@ Features added
 * ``sphinx-build`` command supports i18n console output
 * Add ``app.add_message_catalog()`` and ``sphinx.locale.get_translations()`` to
   support translation for 3rd party extensions
+* helper function ``warning()`` for HTML themes is added
 
 Bugs fixed
 ----------

doc/extdev/index.rst

@@ -113,6 +113,11 @@ The following is a list of deprecated interface.
      - (will be) Removed
      - Alternatives
 
+   * - ``warn()`` (template helper function)
+     - 1.8
+     - 3.0
+     - ``warning()``
+
    * - :confval:`source_parsers`
      - 1.8
      - 3.0

doc/templating.rst

@@ -228,6 +228,9 @@ them to generate links or output multiply used elements.
 
    Return the rendered relation bar.
 
+.. function:: warning(message)
+
+   Emit a warning message.
 
 Global Variables
 ~~~~~~~~~~~~~~~~

sphinx/builders/html.py

@@ -31,7 +31,7 @@ from sphinx import package_dir, __display_version__
 from sphinx.application import ENV_PICKLE_FILENAME
 from sphinx.builders import Builder
 from sphinx.config import string_classes
-from sphinx.deprecation import RemovedInSphinx20Warning
+from sphinx.deprecation import RemovedInSphinx20Warning, RemovedInSphinx30Warning
 from sphinx.environment.adapters.asset import ImageAdapter
 from sphinx.environment.adapters.indexentries import IndexEntries
 from sphinx.environment.adapters.toctree import TocTree
@@ -1001,6 +1001,9 @@ class StandaloneHTMLBuilder(Builder):
         def warn(*args, **kwargs):
             # type: (Any, Any) -> unicode
             """Simple warn() wrapper for themes."""
+            warnings.warn('The template function warn() was deprecated. '
+                          'Use warning() instead.',
+                          RemovedInSphinx30Warning)
             self.warn(*args, **kwargs)
             return ''  # return empty string
         ctx['warn'] = warn

sphinx/jinja2glue.py

@@ -20,6 +20,7 @@ from jinja2.utils import open_if_exists
 from six import string_types
 
 from sphinx.application import TemplateBridge
+from sphinx.util import logging
 from sphinx.util.osutil import mtimes_of_files
 
 if False:
@@ -113,6 +114,17 @@ class idgen(object):
     next = __next__  # Python 2/Jinja compatibility
 
 
+@contextfunction
+def warning(context, message, *args, **kwargs):
+    # type: (Dict, unicode, Any, Any) -> unicode
+    if 'pagename' in context:
+        filename = context.get('pagename') + context.get('file_suffix', '')
+        message = 'in rendering %s: %s' % (filename, message)
+    logger = logging.getLogger('sphinx.themes')
+    logger.warning(message, *args, **kwargs)
+    return ''  # return empty string not to output any values
+
+
 class SphinxFileSystemLoader(FileSystemLoader):
     """
     FileSystemLoader subclass that is not so strict about '..'  entries in
@@ -186,6 +198,7 @@ class BuiltinTemplateLoader(TemplateBridge, BaseLoader):
         self.environment.filters['todim'] = _todim
         self.environment.filters['slice_index'] = _slice_index
         self.environment.globals['debug'] = contextfunction(pformat)
+        self.environment.globals['warning'] = warning
         self.environment.globals['accesskey'] = contextfunction(accesskey)
         self.environment.globals['idgen'] = idgen
         if use_i18n: