Rename add_stylesheet() to add_css_file()

CHANGES

@@ -35,6 +35,7 @@ Deprecated
 * #2157: helper function ``warn()`` for HTML themes is deprecated
 * ``env._nitpick_ignore`` is deprecated
 * ``app.override_domain()`` is deprecated
+* ``app.add_stylesheet()`` is deprecated
 
 For more details, see `deprecation APIs list
 <http://www.sphinx-doc.org/en/master/extdev/index.html#deprecated-apis>`_
@@ -58,7 +59,6 @@ Features added
 * LaTeX: new key ``'fvset'`` for :confval:`latex_elements`. For
   XeLaTeX/LuaLaTeX its default sets ``fanvyvrb`` to use normal, not small,
   fontsize in code-blocks (refs: #4793)
-* ``app.add_stylesheet()`` allows additional attributes
 
 Bugs fixed
 ----------

doc/extdev/index.rst

@@ -113,6 +113,11 @@ The following is a list of deprecated interface.
      - (will be) Removed
      - Alternatives
 
+   * - :meth:`~sphinx.application.Sphinx.add_stylesheet()`
+     - 1.8
+     - 4.0
+     - :meth:`~sphinx.application.Sphinx.add_css_file()`
+
    * - ``sphinx.application.Sphinx.override_domain()``
      - 1.8
      - 3.0

sphinx/application.py

@@ -27,7 +27,9 @@
 import sphinx
 from sphinx import package_dir, locale
 from sphinx.config import Config
-from sphinx.deprecation import RemovedInSphinx20Warning, RemovedInSphinx30Warning
+from sphinx.deprecation import (
+    RemovedInSphinx20Warning, RemovedInSphinx30Warning, RemovedInSphinx40Warning
+)
 from sphinx.environment import BuildEnvironment
 from sphinx.errors import (
     ApplicationError, ConfigError, ExtensionError, VersionRequirementError
@@ -1001,7 +1003,7 @@ def add_javascript(self, filename):
             StandaloneHTMLBuilder.script_files.append(
                 posixpath.join('_static', filename))
 
-    def add_stylesheet(self, filename, **kwargs):
+    def add_css_file(self, filename, **kwargs):
         # type: (unicode, **unicode) -> None
         """Register a stylesheet to include in the HTML output.
 
@@ -1012,14 +1014,14 @@ def add_stylesheet(self, filename, **kwargs):
 
         Example::
 
-            app.add_stylesheet('custom.css')
+            app.add_css_file('custom.css')
             # => <link rel="stylesheet" href="_static/custom.css" type="text/css" />
 
-            app.add_stylesheet('print.css', media='print')
+            app.add_css_file('print.css', media='print')
             # => <link rel="stylesheet" href="_static/print.css"
             #          type="text/css" media="print" />
 
-            app.add_stylesheet('fancy.css', rel='alternate stylesheet', title='fancy')
+            app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
             # => <link rel="alternate stylesheet" href="_static/fancy.css"
             #          type="text/css" title="fancy" />
 
@@ -1033,18 +1035,32 @@ def add_stylesheet(self, filename, **kwargs):
            <https://mdn.io/Web/CSS/Alternative_style_sheets>`__.
 
         .. versionchanged:: 1.8
-           Allows keyword arguments as attributes of link tag.
+           Renamed from ``app.add_stylesheet()``.
+           And it allows keyword arguments as attributes of link tag.
         """
         logger.debug('[app] adding stylesheet: %r', filename)
         if '://' not in filename:
             filename = posixpath.join('_static', filename)
-        if kwargs.pop('alternate', None):
-            warnings.warn('The alternate option for app.add_stylesheet() is deprecated. '
-                          'Please use rel="alternate stylesheet" option instead.',
-                          RemovedInSphinx30Warning)
-            kwargs['rel'] = 'alternate stylesheet'
         self.registry.add_css_files(filename, **kwargs)
 
+    def add_stylesheet(self, filename, alternate=False, title=None):
+        # type: (unicode, bool, unicode) -> None
+        """An alias of :meth:`add_css_file`."""
+        warnings.warn('The app.add_stylesheet() is deprecated. '
+                      'Please use app.add_css_file() instead.',
+                      RemovedInSphinx40Warning)
+
+        attributes = {}  # type: Dict[unicode, unicode]
+        if alternate:
+            attributes['rel'] = 'alternate stylesheet'
+        else:
+            attributes['rel'] = 'stylesheet'
+
+        if title:
+            attributes['title'] = title
+
+        self.add_css_file(filename, **attributes)
+
     def add_latex_package(self, packagename, options=None):
         # type: (unicode, unicode) -> None
         r"""Register a package to include in the LaTeX source code.

sphinx/deprecation.py

@@ -33,6 +33,10 @@ class RemovedInSphinx30Warning(PendingDeprecationWarning):
     pass
 
 
+class RemovedInSphinx40Warning(PendingDeprecationWarning):
+    pass
+
+
 RemovedInNextVersionWarning = RemovedInSphinx18Warning