From a95d716f7f7fa409989a05959e92a87d168460c7 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Wed, 10 Jul 2024 12:07:49 +0200
Subject: [PATCH] Add a class option to the toctree directive (#12524)

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
---
 CHANGES.rst                                   |  2 ++
 doc/usage/restructuredtext/basics.rst         |  6 ++++++
 doc/usage/restructuredtext/directives.rst     |  8 ++++++++
 sphinx/directives/other.py                    |  5 ++++-
 tests/test_directives/test_directive_other.py | 12 ++++++++++++
 5 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index cf70dee2f..009ce641e 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -56,6 +56,8 @@ Features added
 
 * #12258: Support ``typing_extensions.Unpack``
   Patch by Bénédikt Tran and Adam Turner.
+* #12524: Add a ``class`` option to the :rst:dir:`toctree` directive.
+  Patch by Tim Hoffmann.
 
 Bugs fixed
 ----------
diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst
index 7aab544e0..761195271 100644
--- a/doc/usage/restructuredtext/basics.rst
+++ b/doc/usage/restructuredtext/basics.rst
@@ -380,6 +380,12 @@ Docutils supports the following directives:
        When the default domain contains a ``class`` directive, this directive
        will be shadowed.  Therefore, Sphinx re-exports it as ``rst-class``.
 
+    .. tip::
+
+       If you want to add a class to a directive,
+       you may consider the ``:class:`` :dudir:`option <common-options>` instead,
+       which is supported by most directives and allows for a more compact notation.
+
 * HTML specifics:
 
   - :dudir:`meta`
diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst
index ff425246f..73fb9c4ef 100644
--- a/doc/usage/restructuredtext/directives.rst
+++ b/doc/usage/restructuredtext/directives.rst
@@ -124,6 +124,14 @@ tables of contents.  The ``toctree`` directive is the central element.
 
          foo
 
+   As with :dudir:`most directives <common-options>`,
+   you can use the ``class`` option to assign `class attributes`_::
+
+      .. toctree::
+         :class: custom-toc
+
+   .. _class attributes: https://docutils.sourceforge.io/docs/ref/doctree.html#classes
+
    If you want only the titles of documents in the tree to show up, not other
    headings of the same level, you can use the ``titlesonly`` option::
 
diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py
index 7fa12f74e..d7184d73f 100644
--- a/sphinx/directives/other.py
+++ b/sphinx/directives/other.py
@@ -53,6 +53,7 @@ class TocTree(SphinxDirective):
     option_spec = {
         'maxdepth': int,
         'name': directives.unchanged,
+        'class': directives.class_option,
         'caption': directives.unchanged_required,
         'glob': directives.flag,
         'hidden': directives.flag,
@@ -78,7 +79,9 @@ class TocTree(SphinxDirective):
         subnode['numbered'] = self.options.get('numbered', 0)
         subnode['titlesonly'] = 'titlesonly' in self.options
         self.set_source_info(subnode)
-        wrappernode = nodes.compound(classes=['toctree-wrapper'])
+        wrappernode = nodes.compound(
+            classes=['toctree-wrapper', *self.options.get('class', ())],
+        )
         wrappernode.append(subnode)
         self.add_name(wrappernode)
 
diff --git a/tests/test_directives/test_directive_other.py b/tests/test_directives/test_directive_other.py
index 1feb251c5..e00e2914d 100644
--- a/tests/test_directives/test_directive_other.py
+++ b/tests/test_directives/test_directive_other.py
@@ -136,6 +136,18 @@ def test_reversed_toctree(app):
                 includefiles=['baz', 'bar/index', 'foo'])
 
 
+@pytest.mark.sphinx(testroot='toctree-glob')
+def test_toctree_class(app):
+    text = ('.. toctree::\n'
+            '   :class: custom-toc\n'
+            '\n'
+            '   foo\n')
+    app.env.find_files(app.config, app.builder)
+    doctree = restructuredtext.parse(app, text, 'index')
+    assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
+    assert doctree[0].attributes['classes'] == ['toctree-wrapper', 'custom-toc']
+
+
 @pytest.mark.sphinx(testroot='toctree-glob')
 def test_toctree_twice(app):
     text = (".. toctree::\n"