Merge pull request #1767 from Jellby/master

Allow setting 'rel' and 'title' attributes for stylesheets.

doc/extdev/appapi.rst

@@ -302,7 +302,7 @@ package.
 
    .. versionadded:: 0.5
 
-.. method:: Sphinx.add_stylesheet(filename)
+.. method:: Sphinx.add_stylesheet(filename, alternate=None, title=None)
 
    Add *filename* to the list of CSS files that the default HTML template will
    include.  Like for :meth:`add_javascript`, the filename must be relative to
@@ -310,6 +310,12 @@ package.
 
    .. versionadded:: 1.0
 
+   .. versionchanged:: 1.6
+      Optional ``alternate`` and/or ``title`` attributes can be supplied with
+      the *alternate* (of boolean type) and *title* (a string) arguments. The
+      default is no title and *alternate*=``False`` (see `this explanation
+      <https://developer.mozilla.org/en-US/docs/Web/CSS/Alternative_style_sheets>`_).
+
 .. method:: Sphinx.add_latex_package(packagename, options=None)
 
    Add *packagename* to the list of packages that LaTeX source code will include.

doc/templating.rst

@@ -200,11 +200,6 @@ Overriding works like this::
 
       {% set script_files = script_files + ["_static/myscript.js"] %}
 
-.. data:: css_files
-
-   Similar to :data:`script_files`, for CSS files.
-
-
 Helper Functions
 ~~~~~~~~~~~~~~~~
 

sphinx/application.py

@@ -735,15 +735,18 @@ class Sphinx(object):
             StandaloneHTMLBuilder.script_files.append(
                 posixpath.join('_static', filename))
 
-    def add_stylesheet(self, filename):
-        # type: (unicode) -> None
+    def add_stylesheet(self, filename, alternate=False, title=None):
+        # type: (unicode, bool, unicode) -> None
         logger.debug('[app] adding stylesheet: %r', filename)
         from sphinx.builders.html import StandaloneHTMLBuilder
-        if '://' in filename:
-            StandaloneHTMLBuilder.css_files.append(filename)
-        else:
-            StandaloneHTMLBuilder.css_files.append(
-                posixpath.join('_static', filename))
+        props = {'rel': 'stylesheet',
+                 'filename': filename,
+                 'title': title}  # type: Dict[unicode, unicode]
+        if '://' not in filename:
+            props['filename'] = posixpath.join('_static', filename)
+        if alternate:
+            props['rel'] = 'alternate stylesheet'
+        StandaloneHTMLBuilder.css_files.append(props)
 
     def add_latex_package(self, packagename, options=None):
         # type: (unicode, unicode) -> None

sphinx/builders/html.py

@@ -113,8 +113,8 @@ class StandaloneHTMLBuilder(Builder):
     # This is a class attribute because it is mutated by Sphinx.add_javascript.
     script_files = ['_static/jquery.js', '_static/underscore.js',
                     '_static/doctools.js']  # type: List[unicode]
-    # Dito for this one.
-    css_files = []  # type: List[unicode]
+    # Ditto for this one (Sphinx.add_stylesheet).
+    css_files = []  # type: List[Dict[unicode, unicode]]
 
     imgpath = None          # type: unicode
     domain_indices = []     # type: List[Tuple[unicode, Type[Index], List[Tuple[unicode, List[List[Union[unicode, int]]]]], bool]]  # NOQA

sphinx/themes/basic/layout.html

@@ -105,8 +105,8 @@
 {%- macro css() %}
     <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
     <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
-    {%- for cssfile in css_files %}
-    <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
+    {%- for css in css_files %}
+    <link rel="{{ css.rel }}" href="{{ pathto(css.filename, 1) }}" type="text/css"{% if css.title is not none %} title="{{ css.title }}"{% endif %} />
     {%- endfor %}
 {%- endmacro %}
 
@@ -117,9 +117,13 @@
     {%- block htmltitle %}
     <title>{{ title|striptags|e }}{{ titlesuffix }}</title>
     {%- endblock %}
+    {%- block csss %}
     {{ css() }}
+    {%- endblock %}
     {%- if not embedded %}
+    {%- block scripts %}
     {{ script() }}
+    {%- endblock %}
     {%- if use_opensearch %}
     <link rel="search" type="application/opensearchdescription+xml"
           title="{% trans docstitle=docstitle|e %}Search within {{ docstitle }}{% endtrans %}"

sphinx/themes/scrolls/layout.html

@@ -10,7 +10,10 @@
 #}
 {%- extends "basic/layout.html" %}
 {% set script_files = script_files + ['_static/theme_extras.js'] %}
-{% set css_files = css_files + ['_static/print.css'] %}
+{%- block csss %}
+  {{ super() }}
+    <link rel="stylesheet" href="_static/print.css" type="text/css" />
+{%- endblock %}
 {# do not display relbars #}
 {% block relbar1 %}{% endblock %}
 {% block relbar2 %}{% endblock %}

tests/roots/test-stylesheets/_templates/layout.html

@@ -0,0 +1,8 @@
+{% extends "!layout.html" %}
+{%- block csss %}
+  {{ super() }}
+    <link rel="stylesheet" href="_static/more_persistent.css" type="text/css" />
+    <link rel="stylesheet" href="_static/more_default.css" type="text/css" title="Default" />
+    <link rel="alternate stylesheet" href="_static/more_alternate1.css" type="text/css" title="Alternate" />
+    <link rel="alternate stylesheet" href="_static/more_alternate2.css" type="text/css" />
+{%- endblock %}

tests/roots/test-stylesheets/conf.py

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+
+master_doc = 'index'
+html_theme = 'classic'
+templates_path = ['_templates']
+
+def setup(app):
+    app.add_stylesheet('persistent.css')
+    app.add_stylesheet('default.css', title="Default")
+    app.add_stylesheet('alternate1.css', title="Alternate", alternate=True)
+    app.add_stylesheet('alternate2.css', alternate=True)
+

tests/roots/test-stylesheets/index.rst

@@ -0,0 +1,4 @@
+test-stylesheets
+================
+
+Lorem ipsum dolor

tests/test_build_html.py

@@ -1194,3 +1194,33 @@ def test_html_raw_directive(app, status, warning):
     # with substitution
     assert '<p>HTML: abc def ghi</p>' in result
     assert '<p>LaTeX: abc  ghi</p>' in result
+
+
+@pytest.mark.parametrize("fname,expect", flat_dict({
+    'index.html': [
+        (".//link[@href='_static/persistent.css']"
+                "[@rel='stylesheet']", '', True),
+        (".//link[@href='_static/default.css']"
+                "[@rel='stylesheet']"
+                "[@title='Default']", '', True),
+        (".//link[@href='_static/alternate1.css']"
+                "[@rel='alternate stylesheet']"
+                "[@title='Alternate']", '', True),
+        (".//link[@href='_static/alternate2.css']"
+                "[@rel='alternate stylesheet']", '', True),
+        (".//link[@href='_static/more_persistent.css']"
+                "[@rel='stylesheet']", '', True),
+        (".//link[@href='_static/more_default.css']"
+                "[@rel='stylesheet']"
+                "[@title='Default']", '', True),
+        (".//link[@href='_static/more_alternate1.css']"
+                "[@rel='alternate stylesheet']"
+                "[@title='Alternate']", '', True),
+        (".//link[@href='_static/more_alternate2.css']"
+                "[@rel='alternate stylesheet']", '', True),
+    ],
+}))
+@pytest.mark.sphinx('html', testroot='stylesheets')
+def test_alternate_stylesheets(app, cached_etree_parse, fname, expect):
+    app.build()
+    check_xpath(cached_etree_parse(app.outdir / fname), fname, *expect)