Support theme configuration via theme.toml files

doc/_themes/sphinx13/theme.toml

@@ -0,0 +1,4 @@
+[theme]
+inherit = "basic"
+pygments_style = { default = "default" }
+sidebars = []

doc/development/theming.rst

@@ -30,11 +30,82 @@ Creating themes
 Themes take the form of either a directory or a zipfile (whose name is the
 theme name), containing the following:
 
-* A :file:`theme.conf` file.
+* Either a :file:`theme.toml` file (preferred) or a :file:`theme.conf` file.
 * HTML templates, if needed.
 * A ``static/`` directory containing any static files that will be copied to the
   output static directory on build.  These can be images, styles, script files.
 
+Theme configuration (``theme.toml``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :file:`theme.toml` file is a TOML_ document,
+containing two tables: ``[theme]`` and ``[options]``.
+
+The ``[theme]`` table defines the theme's settings:
+
+* **inherit** (string): The name of the base theme from which to inherit
+  settings, options, templates, and static files.
+  All static files from theme 'ancestors' will be used.
+  The theme will use all options defined in inherited themes.
+  Finally, inherited themes will be used to locate missing templates
+  (for example, if ``"basic"`` is used as the base theme, most templates will
+  already be defined).
+
+  If set to ``"none"``, the theme will not inherit from any other theme.
+  Inheritance is recursive, forming a chain of inherited themes
+  (e.g. ``default`` -> ``classic`` -> ``basic`` -> ``none``).
+
+* **stylesheets** (list of strings): A list of CSS filenames which will be
+  included in generated HTML header.
+  Setting the   :confval:`html_style` config value will override this setting.
+
+  Other mechanisms for including multiple stylesheets include ``@import`` in CSS
+  or using a custom HTML template with appropriate ``<link rel="stylesheet">`` tags.
+
+* **sidebars** (list of strings): A list of sidebar templates.
+  This can be overridden by the user via the :confval:`html_sidebars` config value.
+
+* **pygments_style** (table): A TOML table defining the names of Pygments styles
+  to use for highlighting syntax.
+  The table has two recognised keys: ``default`` and ``dark``.
+  The style defined in the ``dark`` key will be used when
+  the CSS media query ``(prefers-color-scheme: dark)`` evaluates to true.
+
+  ``[theme.pygments_style.default]`` can be overridden by the user via the
+  :confval:`pygments_style` config value.
+
+The ``[options]`` table defines the options for the theme.
+It is structured such that each key-value pair corresponds to a variable name
+and the corresponding default value.
+These options can be overridden by the user in :confval:`html_theme_options`
+and are accessible from all templates as ``theme_<name>``.
+
+.. versionadded:: 7.3
+   ``theme.toml`` support.
+
+.. _TOML: https://toml.io/en/
+
+Exemplar :file:`theme.toml` file:
+
+.. code-block:: toml
+
+   [theme]
+   inherit = "basic"
+   stylesheets = [
+       "main-CSS-stylesheet.css",
+   ]
+   sidebars = [
+       "localtoc.html",
+       "relations.html",
+       "sourcelink.html",
+       "searchbox.html",
+   ]
+   # Style names from https://pygments.org/styles/
+   pygments_style = { default = "style_name", dark = "dark_style" }
+
+   [options]
+   variable = "default value"
+
 Theme configuration (``theme.conf``)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -89,6 +160,24 @@ Python :mod:`configparser` module) and has the following structure:
 
    The stylesheet setting accepts multiple CSS filenames
 
+Convert ``theme.conf`` to ``theme.toml``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+INI-style theme configuration files (``theme.conf``) can be converted to TOML
+via a helper programme distributed with Sphinx.
+This is intended for one-time use, and may be removed without notice in a future
+version of Sphinx.
+
+.. code-block:: console
+
+   $ python -m sphinx.theming conf_to_toml [THEME DIRECTORY PATH]
+
+The required argument is a path to a directory containing a ``theme.conf`` file.
+The programme will write a ``theme.toml`` file in the same directory,
+and will not modify the original ``theme.conf`` file.
+
+.. versionadded:: 7.3
+
 .. _distribute-your-theme:
 
 Distribute your theme as a Python package

doc/usage/theming.rst

@@ -56,7 +56,7 @@ page's top and bottom), add the following :file:`conf.py`::
 
 If the theme does not come with Sphinx, it can be in two static forms or as a
 Python package. For the static forms, either a directory (containing
-:file:`theme.conf` and other needed files), or a zip file with the same
+:file:`theme.toml` and other needed files), or a zip file with the same
 contents is supported. The directory or zipfile must be put where Sphinx can
 find it; for this there is the config value :confval:`html_theme_path`. This
 can be a list of directories, relative to the directory containing

sphinx/themes/agogo/theme.toml

@@ -0,0 +1,22 @@
+[theme]
+inherit = "basic"
+stylesheets = [
+    "agogo.css",
+]
+pygments_style = { default = "tango" }
+
+[options]
+bodyfont = "\"Verdana\", Arial, sans-serif"
+headerfont = "\"Georgia\", \"Times New Roman\", serif"
+pagewidth = "70em"
+documentwidth = "50em"
+rightsidebar = "true"
+sidebarwidth = "20em"
+bgcolor = "#eeeeec"
+headerbg = "#555573 url(bgtop.png) top left repeat-x"
+footerbg = "url(bgfooter.png) top left repeat-x"
+linkcolor = "#ce5c00"
+headercolor1 = "#204a87"
+headercolor2 = "#3465a4"
+headerlinkcolor = "#fcaf3e"
+textalign = "justify"

sphinx/themes/basic/theme.toml

@@ -0,0 +1,23 @@
+[theme]
+inherit = "none"
+stylesheets = [
+    "basic.css",
+]
+sidebars = [
+    "localtoc.html",
+    "relations.html",
+    "sourcelink.html",
+    "searchbox.html",
+]
+pygments_style = { default = "none" }
+
+[options]
+nosidebar = "false"
+sidebarwidth = "230"
+body_min_width = "360"
+body_max_width = "800"
+navigation_with_keys = "False"
+enable_search_shortcuts = "True"
+globaltoc_collapse = "true"
+globaltoc_includehidden = "false"
+globaltoc_maxdepth = ""

sphinx/themes/bizstyle/theme.toml

@@ -0,0 +1,12 @@
+[theme]
+inherit = "basic"
+stylesheets = [
+    "bizstyle.css",
+]
+pygments_style = { default = "friendly" }
+
+[options]
+rightsidebar = "false"
+sidebarwidth = "210"
+
+maincolor = "#336699"

sphinx/themes/classic/theme.toml

@@ -0,0 +1,34 @@
+[theme]
+inherit = "basic"
+stylesheets = [
+    "classic.css",
+]
+pygments_style = { default = "sphinx" }
+
+[options]
+rightsidebar = "false"
+stickysidebar = "false"
+collapsiblesidebar = "false"
+externalrefs = "false"
+
+footerbgcolor    = "#11303d"
+footertextcolor  = "#ffffff"
+sidebarbgcolor   = "#1c4e63"
+sidebarbtncolor  = "#3c6e83"
+sidebartextcolor = "#ffffff"
+sidebarlinkcolor = "#98dbcc"
+relbarbgcolor    = "#133f52"
+relbartextcolor  = "#ffffff"
+relbarlinkcolor  = "#ffffff"
+bgcolor          = "#ffffff"
+textcolor        = "#000000"
+headbgcolor      = "#f2f2f2"
+headtextcolor    = "#20435c"
+headlinkcolor    = "#c60f0f"
+linkcolor        = "#355f7c"
+visitedlinkcolor = "#551a8b"
+codebgcolor      = "unset"
+codetextcolor    = "unset"
+
+bodyfont = "sans-serif"
+headfont = "'Trebuchet MS', sans-serif"

sphinx/themes/default/theme.toml

@@ -0,0 +1,2 @@
+[theme]
+inherit = "classic"

sphinx/themes/epub/theme.toml

@@ -0,0 +1,10 @@
+[theme]
+inherit = "basic"
+stylesheets = [
+    "epub.css",
+]
+pygments_style = { default = "none" }
+
+[options]
+relbar1 = "true"
+footer = "true"

sphinx/themes/haiku/theme.toml

@@ -0,0 +1,16 @@
+[theme]
+inherit = "basic"
+stylesheets = [
+    "haiku.css",
+]
+pygments_style = { default = "autumn" }
+
+[options]
+full_logo        = "false"
+body_min_width   = "59em"
+body_max_width   = "70em"
+textcolor        = "#333333"
+headingcolor     = "#0c3762"
+linkcolor        = "#dc3c01"
+visitedlinkcolor = "#551a8b"
+hoverlinkcolor   = "#ff4500"

sphinx/themes/nature/theme.toml

@@ -0,0 +1,6 @@
+[theme]
+inherit = "basic"
+stylesheets = [
+    "nature.css",
+]
+pygments_style = { default = "tango" }

sphinx/themes/nonav/theme.toml

@@ -0,0 +1,10 @@
+[theme]
+inherit = "basic"
+stylesheets = [
+    "nonav.css",
+]
+pygments_style = { default = "none" }
+
+[options]
+relbar1 = "true"
+footer = "true"