Allow specifying multiple CSS files in themes

CHANGES

@@ -13,6 +13,9 @@ Deprecated
 Features added
 --------------
 
+* #10444: html theme: Allow to specify multiple CSS files via ``stylesheet``
+  setting on ``theme.conf``
+
 Bugs fixed
 ----------
 

doc/development/theming.rst

@@ -56,10 +56,10 @@ Python :mod:`ConfigParser` module) and has the following structure:
   want to also inherit the stylesheet, include it via CSS' ``@import`` in your
   own.
 
-* The **stylesheet** setting gives the name of a CSS file which will be
-  referenced in the HTML header.  If you need more than one CSS file, either
-  include one from the other via CSS' ``@import``, or use a custom HTML template
-  that adds ``<link rel="stylesheet">`` tags as necessary.  Setting the
+* The **stylesheet** setting gives a list of CSS filenames separated commas which
+  will be referenced in the HTML header.  You can also use CSS' ``@import``
+  technique to include one from the other, or use a custom HTML template that
+  adds ``<link rel="stylesheet">`` tags as necessary.  Setting the
   :confval:`html_style` config value will override this setting.
 
 * The **pygments_style** setting gives the name of a Pygments style to use for
@@ -82,6 +82,9 @@ Python :mod:`ConfigParser` module) and has the following structure:
 .. versionadded:: 1.7
    sidebar settings
 
+.. versionchanged:: 5.1
+
+   The stylesheet setting accepts multiple CSS filenames
 
 .. _distribute-your-theme:
 

sphinx/builders/html/__init__.py

@@ -272,6 +272,15 @@ def _get_style_filename(self) -> str:
         else:
             return 'default.css'
 
+    def get_style_filenames(self) -> str:
+        if self.config.html_style is not None:
+            return [self.config.html_style]
+        elif self.theme:
+            stylesheet = self.theme.get_config('theme', 'stylesheet')
+            return [s.strip() for s in stylesheet.split(',')]
+        else:
+            return ['default.css']
+
     def get_theme_config(self) -> Tuple[str, Dict]:
         return self.config.html_theme, self.config.html_theme_options
 
@@ -309,7 +318,9 @@ def init_highlighter(self) -> None:
     def init_css_files(self) -> None:
         self.css_files = []
         self.add_css_file('pygments.css', priority=200)
-        self.add_css_file(self._get_style_filename(), priority=200)
+
+        for filename in self.get_style_filenames():
+            self.add_css_file(filename, priority=200)
 
         for filename, attrs in self.app.registry.css_files:
             self.add_css_file(filename, **attrs)

tests/roots/test-build-html-theme-having-multiple-stylesheets/_themes/mytheme/theme.conf

@@ -0,0 +1,3 @@
+[theme]
+inherit = basic
+stylesheet = mytheme.css, extra.css

tests/roots/test-build-html-theme-having-multiple-stylesheets/conf.py

@@ -0,0 +1,2 @@
+html_theme_path = ['_themes']
+html_theme = 'mytheme'

tests/roots/test-build-html-theme-having-multiple-stylesheets/index.rst

@@ -0,0 +1,2 @@
+test-build-html-theme-having-multiple-stylesheets
+=================================================

tests/test_build_html.py

@@ -1735,3 +1735,12 @@ def test_html_code_role(app):
     assert ('<div class="highlight-python notranslate">' +
             '<div class="highlight"><pre><span></span>' +
             common_content) in content
+
+
+@pytest.mark.sphinx('html', testroot='build-html-theme-having-multiple-stylesheets')
+def test_theme_having_multiple_stylesheets(app):
+    app.build()
+    content = (app.outdir / 'index.html').read_text(encoding='utf-8')
+
+    assert '<link rel="stylesheet" type="text/css" href="_static/mytheme.css" />' in content
+    assert '<link rel="stylesheet" type="text/css" href="_static/extra.css" />' in content