From 2ab9a5f6b873c19eab00832a0e7116c51e1af65e Mon Sep 17 00:00:00 2001
From: James Knight <james.d.knight@live.com>
Date: Sat, 15 Jul 2023 13:28:30 -0400
Subject: [PATCH] doc: document new individual code block theme override

Signed-off-by: James Knight <james.d.knight@live.com>
---
 doc/_themes/sphinx13b/static/sphinx13b.css |  6 +++++
 doc/configuration.rst                      | 17 ++++++++----
 doc/guide-class-hints.rst                  | 31 ++++++++++++++++++++++
 doc/guides.rst                             |  1 +
 4 files changed, 50 insertions(+), 5 deletions(-)
 create mode 100644 doc/guide-class-hints.rst

diff --git a/doc/_themes/sphinx13b/static/sphinx13b.css b/doc/_themes/sphinx13b/static/sphinx13b.css
index 9823f3b6..f658ea38 100644
--- a/doc/_themes/sphinx13b/static/sphinx13b.css
+++ b/doc/_themes/sphinx13b/static/sphinx13b.css
@@ -486,6 +486,12 @@ code.literal {
     color: #CE0000;
 }
 
+h1 code.literal,
+h2 code.literal,
+h3 code.literal,
+h4 code.literal,
+h5 code.literal,
+h6 code.literal,
 .sphinxsidebarwrapper code.literal {
     border: unset;
     padding: unset;
diff --git a/doc/configuration.rst b/doc/configuration.rst
index fe420519..6e968072 100644
--- a/doc/configuration.rst
+++ b/doc/configuration.rst
@@ -213,20 +213,27 @@ Generic configuration
 
     See also |confluence_publish_prefix|_.
 
+.. |confluence_code_block_theme| replace:: ``confluence_code_block_theme``
+.. _confluence_code_block_theme:
+
 .. confval:: confluence_code_block_theme
 
     .. versionadded:: 2.2
 
-    Specifies the color scheme to use when displaying a Confluence code block macro.
+    .. note::
+
+        This option is only supported using the ``v1``
+        :ref:`editor <confluence_editor>`.
+
+    Specifies the color scheme to use when displaying a Confluence code
+    block macro.
 
     .. code-block:: python
 
         confluence_code_block_theme = 'Midnight'
 
-    .. note::
-
-        This option is only supported using the ``v1``
-        :ref:`editor <confluence_editor>`.
+    For configuring the theme on individual code blocks, see
+    :ref:`class hints <confluence_class_hints>`.
 
 .. confval:: confluence_default_alignment
 
diff --git a/doc/guide-class-hints.rst b/doc/guide-class-hints.rst
new file mode 100644
index 00000000..3e1a559b
--- /dev/null
+++ b/doc/guide-class-hints.rst
@@ -0,0 +1,31 @@
+.. index:: Class hints
+
+.. _confluence_class_hints:
+
+Class hints
+===========
+
+The following outlines all available class-related hints supported by the
+Confluence builder extension.
+
+``confluence-theme-<theme>``
+----------------------------
+
+.. versionadded:: 2.2
+
+When this class hint is applied to a literal/code block, this provides the
+ability to override the theme configured for an individual code-block macro.
+For example:
+
+.. code-block:: none
+
+    .. code-block:: python
+        :class: confluence-theme-FadeToGrey
+
+        def main():
+            print 'Hello, world!'
+
+        if __name__ == '__main__':
+            main()
+
+See also :ref:`confluence_code_block_theme <confluence_code_block_theme>`.
diff --git a/doc/guides.rst b/doc/guides.rst
index c5448f8c..9f238b80 100644
--- a/doc/guides.rst
+++ b/doc/guides.rst
@@ -7,6 +7,7 @@ the Confluence Builder extension in a Sphinx-enabled environment.
 .. toctree::
     :maxdepth: 1
 
+    guide-class-hints
     guide-collapse
     guide-math
     guide-ci