[PATCH RFC 00/11] use toctree :caption: for ToC headings

[PATCH RFC 00/11] use toctree :caption: for ToC headings

[Vegard Nossum]

Hi,

This patch series replaces some instances of 'class:: toc-title' with
toctree's :caption: attribute, see the last patch in the series for
some more rationale/explanation.

There are some dependencies here: the first patch is necessary for the
headings in following patches to be styled correctly with the alabaster
theme (rtd_sphinx already has it), and the last patch depends on most
of the previous patches to not use the old .toc-title class anymore.

Assuming people agree with the general direction, I thought maybe the
easiest thing would be to collect maintainer acks in this round and
then for me to resubmit everything to the documentation tree/maintainer
in one go.


Vegard

---

Vegard Nossum (11):
  docs: style toctree captions as headings
  doc: userspace-api: properly format ToC headings
  media: admin-guide: properly format ToC heading
  crypto: doc: properly format ToC headings
  Documentation: dev-tools: properly format ToC headingss
  docs: driver-api: properly format ToC headings
  input: docs: properly format ToC headings
  doc: misc-device: properly format ToC heading
  media: doc: properly format ToC headings
  docs: use toctree :caption: and move introduction
  docs: remove .toc-title class

 Documentation/admin-guide/media/index.rst     | 10 +---------
 Documentation/crypto/api.rst                  |  5 +----
 Documentation/crypto/index.rst                |  5 +----
 Documentation/dev-tools/index.rst             |  5 +----
 Documentation/driver-api/index.rst            |  5 +----
 Documentation/driver-api/media/index.rst      |  7 +------
 Documentation/driver-api/mei/index.rst        |  7 +------
 Documentation/driver-api/pci/index.rst        |  5 +----
 Documentation/input/input_kapi.rst            |  5 +----
 Documentation/input/input_uapi.rst            |  5 +----
 Documentation/input/joydev/index.rst          |  5 +----
 Documentation/misc-devices/index.rst          |  5 +----
 Documentation/process/development-process.rst | 19 +++++++++----------
 Documentation/sphinx-static/custom.css        |  3 +++
 .../sphinx-static/theme_overrides.css         |  5 -----
 .../it_IT/process/development-process.rst     | 19 +++++++++----------
 .../translations/zh_CN/dev-tools/index.rst    |  5 +----
 .../zh_CN/driver-api/gpio/index.rst           |  3 +--
 .../translations/zh_CN/driver-api/index.rst   |  5 +----
 .../zh_CN/process/development-process.rst     |  5 ++---
 .../zh_CN/userspace-api/index.rst             |  5 +----
 .../zh_TW/process/development-process.rst     |  5 ++---
 Documentation/userspace-api/index.rst         |  5 +----
 .../userspace-api/media/cec/cec-api.rst       |  7 +------
 .../userspace-api/media/drivers/index.rst     |  7 +------
 .../userspace-api/media/dvb/dvbapi.rst        |  7 +------
 Documentation/userspace-api/media/index.rst   |  7 +------
 .../media/mediactl/media-controller.rst       |  7 +------
 .../media/rc/remote_controllers.rst           |  7 +------
 .../userspace-api/media/v4l/v4l2.rst          |  7 +------
 30 files changed, 49 insertions(+), 148 deletions(-)

-- 
2.34.1

[PATCH RFC 01/11] docs: style toctree captions as headings

[Vegard Nossum]

The rtd theme already styles toctree captions as headings, but the
alabaster theme doesn't. Add this in.

Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
---
 Documentation/sphinx-static/custom.css | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index 084a884f6fb7..c7439349dda6 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -8,6 +8,9 @@ div.body h1 { font-size: 180%; }
 div.body h2 { font-size: 150%; }
 div.body h3 { font-size: 130%; }
 
+/* toctree captions are styled like h2 */
+div.toctree-wrapper p.caption[role=heading] { font-size: 150%; }
+
 /* Tighten up the layout slightly */
 div.body { padding: 0 15px 0 10px; }
 div.sphinxsidebarwrapper { padding: 1em 0.4em; }
-- 
2.34.1

[PATCH RFC 02/11] doc: userspace-api: properly format ToC headings

[Vegard Nossum]

"class:: toc-title" was a workaround for older Sphinx versions that are
no longer supported.

The canonical way to add a heading to the ToC is to use :caption:.
Do that.

Cc: Rui Li <me@lirui.org>
Cc: Yanteng Si <siyanteng@loongson.cn>
Cc: Wu XiangCheng <bobwxc@email.cn>
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
---
 Documentation/translations/zh_CN/userspace-api/index.rst | 5 +----
 Documentation/userspace-api/index.rst                    | 5 +----
 2 files changed, 2 insertions(+), 8 deletions(-)

diff --git a/Documentation/translations/zh_CN/userspace-api/index.rst b/Documentation/translations/zh_CN/userspace-api/index.rst
index 5dc0f2e69c17..5b14721c8264 100644
--- a/Documentation/translations/zh_CN/userspace-api/index.rst
+++ b/Documentation/translations/zh_CN/userspace-api/index.rst
@@ -17,11 +17,8 @@ Linux 内核用户空间API指南
 在代码树中仍然可以找到有关用户空间的部分信息。这个手册意在成为这些信息
 聚集的地方。
 
-.. class:: toc-title
-
-	   目录
-
 .. toctree::
+   :caption: 目录
    :maxdepth: 2
 
    no_new_privs
diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst
index 72a65db0c498..5b32a461c2dd 100644
--- a/Documentation/userspace-api/index.rst
+++ b/Documentation/userspace-api/index.rst
@@ -9,11 +9,8 @@ While much of the kernel's user-space API is documented elsewhere
 also be found in the kernel tree itself.  This manual is intended to be the
 place where this information is gathered.
 
-.. class:: toc-title
-
-	   Table of contents
-
 .. toctree::
+   :caption: Table of contents
    :maxdepth: 2
 
    no_new_privs
-- 
2.34.1

[PATCH RFC 03/11] media: admin-guide: properly format ToC heading

[Vegard Nossum]

"class:: toc-title" was a workaround for older Sphinx versions that are
no longer supported.

The canonical way to add a heading to the ToC is to use :caption:.
Do that.

Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
---
 Documentation/admin-guide/media/index.rst | 10 +---------
 1 file changed, 1 insertion(+), 9 deletions(-)

diff --git a/Documentation/admin-guide/media/index.rst b/Documentation/admin-guide/media/index.rst
index 43f4a292b245..be7e0e4482ca 100644
--- a/Documentation/admin-guide/media/index.rst
+++ b/Documentation/admin-guide/media/index.rst
@@ -20,16 +20,8 @@ Documentation/driver-api/media/index.rst
   - for driver development information and Kernel APIs used by
     media devices;
 
-The media subsystem
-===================
-
-.. only:: html
-
-    .. class:: toc-title
-
-        Table of Contents
-
 .. toctree::
+	:caption: Table of Contents
 	:maxdepth: 2
 	:numbered:
 
-- 
2.34.1

[PATCH RFC 04/11] crypto: doc: properly format ToC headings

[Vegard Nossum]

"class:: toc-title" was a workaround for older Sphinx versions that are
no longer supported.

The canonical way to add a heading to the ToC is to use :caption:.
Do that.

Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Stephan Mueller <smueller@chronox.de>
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
---
 Documentation/crypto/api.rst   | 5 +----
 Documentation/crypto/index.rst | 5 +----
 2 files changed, 2 insertions(+), 8 deletions(-)

diff --git a/Documentation/crypto/api.rst b/Documentation/crypto/api.rst
index b91b31736df8..ff31c30561d4 100644
--- a/Documentation/crypto/api.rst
+++ b/Documentation/crypto/api.rst
@@ -1,11 +1,8 @@
 Programming Interface
 =====================
 
-.. class:: toc-title
-
-	   Table of contents
-
 .. toctree::
+   :caption: Table of contents
    :maxdepth: 2
 
    api-skcipher
diff --git a/Documentation/crypto/index.rst b/Documentation/crypto/index.rst
index da5d5ad2bdf3..10647c5ae2ea 100644
--- a/Documentation/crypto/index.rst
+++ b/Documentation/crypto/index.rst
@@ -9,11 +9,8 @@ This documentation outlines the Linux kernel crypto API with its
 concepts, details about developing cipher implementations, employment of the API
 for cryptographic use cases, as well as programming examples.
 
-.. class:: toc-title
-
-	   Table of contents
-
 .. toctree::
+   :caption: Table of contents
    :maxdepth: 2
 
    intro
-- 
2.34.1

[PATCH RFC 05/11] Documentation: dev-tools: properly format ToC headingss

[Vegard Nossum]

"class:: toc-title" was a workaround for older Sphinx versions that are
no longer supported.

The canonical way to add a heading to the ToC is to use :caption:.
Do that.

Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: gaochao <gaochao49@huawei.com>
Cc: Yanteng Si <siyanteng@loongson.cn>
Cc: Wu XiangCheng <bobwxc@email.cn>
Cc: Fangrui Song <maskray@google.com>
Cc: Wan Jiabing <wanjiabing@vivo.com>
Cc: Alex Shi <alexs@kernel.org>
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
---
 Documentation/dev-tools/index.rst                    | 5 +----
 Documentation/translations/zh_CN/dev-tools/index.rst | 5 +----
 2 files changed, 2 insertions(+), 8 deletions(-)

diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst
index 6b0663075dc0..3d2286c683bc 100644
--- a/Documentation/dev-tools/index.rst
+++ b/Documentation/dev-tools/index.rst
@@ -10,11 +10,8 @@ whole; patches welcome!
 A brief overview of testing-specific tools can be found in
 Documentation/dev-tools/testing-overview.rst
 
-.. class:: toc-title
-
-	   Table of contents
-
 .. toctree::
+   :caption: Table of contents
    :maxdepth: 2
 
    testing-overview
diff --git a/Documentation/translations/zh_CN/dev-tools/index.rst b/Documentation/translations/zh_CN/dev-tools/index.rst
index 02577c379007..c2db3e566b1b 100644
--- a/Documentation/translations/zh_CN/dev-tools/index.rst
+++ b/Documentation/translations/zh_CN/dev-tools/index.rst
@@ -14,11 +14,8 @@
 有关测试专用工具的简要概述，参见
 Documentation/translations/zh_CN/dev-tools/testing-overview.rst
 
-.. class:: toc-title
-
-	   目录
-
 .. toctree::
+   :caption: 目录
    :maxdepth: 2
 
    testing-overview
-- 
2.34.1

[PATCH RFC 06/11] docs: driver-api: properly format ToC headings

[Vegard Nossum]

"class:: toc-title" was a workaround for older Sphinx versions that are
no longer supported.

The canonical way to add a heading to the ToC is to use :caption:.
Do that.

Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Richard Cochran <richardcochran@gmail.com>
Cc: SeongJae Park <sj@kernel.org>
Cc: Hans de Goede <hdegoede@redhat.com>
Cc: Armin Wolf <W_Armin@gmx.de>
Cc: Iwona Winiarska <iwona.winiarska@intel.com>
Cc: "Ricardo Cañuelo" <ricardo.canuelo@collabora.com>
Cc: Tomas Winkler <tomas.winkler@intel.com>
Cc: linux-media@vger.kernel.org
Cc: Yanteng Si <siyanteng@loongson.cn>
Cc: Alex Shi <alexs@kernel.org>
Cc: Wu XiangCheng <bobwxc@email.cn>
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
---
 Documentation/driver-api/index.rst                         | 5 +----
 Documentation/driver-api/media/index.rst                   | 7 +------
 Documentation/driver-api/mei/index.rst                     | 7 +------
 Documentation/driver-api/pci/index.rst                     | 5 +----
 Documentation/translations/zh_CN/driver-api/gpio/index.rst | 3 +--
 Documentation/translations/zh_CN/driver-api/index.rst      | 5 +----
 6 files changed, 6 insertions(+), 26 deletions(-)

diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 1e16a40da3ba..4540f79a34a9 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -9,11 +9,8 @@ of device drivers.  This document is an only somewhat organized collection
 of some of those interfaces — it will hopefully get better over time!  The
 available subsections can be seen below.
 
-.. class:: toc-title
-
-	   Table of contents
-
 .. toctree::
+   :caption: Table of contents
    :maxdepth: 2
 
    driver-model/index
diff --git a/Documentation/driver-api/media/index.rst b/Documentation/driver-api/media/index.rst
index 08e206567408..d5593182a3f9 100644
--- a/Documentation/driver-api/media/index.rst
+++ b/Documentation/driver-api/media/index.rst
@@ -20,13 +20,8 @@ Documentation/userspace-api/media/index.rst
   - for the userspace APIs used on media devices.
 
 
-.. only:: html
-
-   .. class:: toc-title
-
-        Table of Contents
-
 .. toctree::
+    :caption: Table of Contents
     :maxdepth: 5
     :numbered:
 
diff --git a/Documentation/driver-api/mei/index.rst b/Documentation/driver-api/mei/index.rst
index 3a22b522ee78..eae6f18f18cf 100644
--- a/Documentation/driver-api/mei/index.rst
+++ b/Documentation/driver-api/mei/index.rst
@@ -9,13 +9,8 @@ Intel(R) Management Engine Interface (Intel(R) MEI)
 **Copyright** |copy| 2019 Intel Corporation
 
 
-.. only:: html
-
-   .. class:: toc-title
-
-        Table of Contents
-
 .. toctree::
+   :caption: Table of Contents
    :maxdepth: 3
 
    mei
diff --git a/Documentation/driver-api/pci/index.rst b/Documentation/driver-api/pci/index.rst
index c6cf1fef61ce..a38e475cdbe3 100644
--- a/Documentation/driver-api/pci/index.rst
+++ b/Documentation/driver-api/pci/index.rst
@@ -4,11 +4,8 @@
 The Linux PCI driver implementer's API guide
 ============================================
 
-.. class:: toc-title
-
-	   Table of contents
-
 .. toctree::
+   :caption: Table of contents
    :maxdepth: 2
 
    pci
diff --git a/Documentation/translations/zh_CN/driver-api/gpio/index.rst b/Documentation/translations/zh_CN/driver-api/gpio/index.rst
index 9ab64e94aced..9a6a14162a6c 100644
--- a/Documentation/translations/zh_CN/driver-api/gpio/index.rst
+++ b/Documentation/translations/zh_CN/driver-api/gpio/index.rst
@@ -14,9 +14,8 @@
 通用型输入/输出（GPIO）
 =======================
 
-目录:
-
 .. toctree::
+   :caption: 目录
    :maxdepth: 2
 
    legacy
diff --git a/Documentation/translations/zh_CN/driver-api/index.rst b/Documentation/translations/zh_CN/driver-api/index.rst
index ba354e1f4e6d..92ff1b7fc3d3 100644
--- a/Documentation/translations/zh_CN/driver-api/index.rst
+++ b/Documentation/translations/zh_CN/driver-api/index.rst
@@ -17,11 +17,8 @@ Linux驱动实现者的API指南
 内核提供了各种各样的接口来支持设备驱动的开发。这份文档只是对其中一些接口进行了
 一定程度的整理——希望随着时间的推移，它能变得更好！可用的小节可以在下面看到。
 
-.. class:: toc-title
-
-	   目录列表：
-
 .. toctree::
+   :caption: 目录列表
    :maxdepth: 2
 
    gpio/index
-- 
2.34.1

[PATCH RFC 07/11] input: docs: properly format ToC headings

[Vegard Nossum]

"class:: toc-title" was a workaround for older Sphinx versions that are
no longer supported.

The canonical way to add a heading to the ToC is to use :caption:.
Do that.

Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Cc: linux-input@vger.kernel.org
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
---
 Documentation/input/input_kapi.rst   | 5 +----
 Documentation/input/input_uapi.rst   | 5 +----
 Documentation/input/joydev/index.rst | 5 +----
 3 files changed, 3 insertions(+), 12 deletions(-)

diff --git a/Documentation/input/input_kapi.rst b/Documentation/input/input_kapi.rst
index 41f1b7e6b78e..9937522daa9b 100644
--- a/Documentation/input/input_kapi.rst
+++ b/Documentation/input/input_kapi.rst
@@ -4,11 +4,8 @@
 Linux Input Subsystem kernel API
 ################################
 
-.. class:: toc-title
-
-        Table of Contents
-
 .. toctree::
+   :caption: Table of Contents
    :maxdepth: 2
    :numbered:
 
diff --git a/Documentation/input/input_uapi.rst b/Documentation/input/input_uapi.rst
index 4a0391609327..8275b4223a84 100644
--- a/Documentation/input/input_uapi.rst
+++ b/Documentation/input/input_uapi.rst
@@ -4,11 +4,8 @@
 Linux Input Subsystem userspace API
 ###################################
 
-.. class:: toc-title
-
-        Table of Contents
-
 .. toctree::
+   :caption: Table of Contents
    :maxdepth: 2
    :numbered:
 
diff --git a/Documentation/input/joydev/index.rst b/Documentation/input/joydev/index.rst
index ebcff43056e2..d03d6f6cbfab 100644
--- a/Documentation/input/joydev/index.rst
+++ b/Documentation/input/joydev/index.rst
@@ -6,11 +6,8 @@ Linux Joystick support
 
 :Copyright: |copy| 1996-2000 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE
 
-.. class:: toc-title
-
-	Table of Contents
-
 .. toctree::
+	:caption: Table of Contents
 	:maxdepth: 3
 
 	joystick
-- 
2.34.1

[PATCH RFC 08/11] doc: misc-device: properly format ToC heading

[Vegard Nossum]

"class:: toc-title" was a workaround for older Sphinx versions that are
no longer supported.

The canonical way to add a heading to the ToC is to use :caption:.
Do that.

Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Julien Panis <jpanis@baylibre.com>
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
---
 Documentation/misc-devices/index.rst | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst
index ecc40fbbcfb8..1fc89d664830 100644
--- a/Documentation/misc-devices/index.rst
+++ b/Documentation/misc-devices/index.rst
@@ -7,11 +7,8 @@ Assorted Miscellaneous Devices Documentation
 This documentation contains information for assorted devices that do not
 fit into other categories.
 
-.. class:: toc-title
-
-	   Table of contents
-
 .. toctree::
+   :caption: Table of contents
    :maxdepth: 2
 
    ad525x_dpot
-- 
2.34.1

[PATCH RFC 09/11] media: doc: properly format ToC headings

[Vegard Nossum]

"class:: toc-title" was a workaround for older Sphinx versions that are
no longer supported.

The canonical way to add a heading to the ToC is to use :caption:.
Do that.

Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: linux-media@vger.kernel.org
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
---
 Documentation/userspace-api/media/cec/cec-api.rst          | 7 +------
 Documentation/userspace-api/media/drivers/index.rst        | 7 +------
 Documentation/userspace-api/media/dvb/dvbapi.rst           | 7 +------
 Documentation/userspace-api/media/index.rst                | 7 +------
 .../userspace-api/media/mediactl/media-controller.rst      | 7 +------
 .../userspace-api/media/rc/remote_controllers.rst          | 7 +------
 Documentation/userspace-api/media/v4l/v4l2.rst             | 7 +------
 7 files changed, 7 insertions(+), 42 deletions(-)

diff --git a/Documentation/userspace-api/media/cec/cec-api.rst b/Documentation/userspace-api/media/cec/cec-api.rst
index 4d229ed8a1d9..578303d484f3 100644
--- a/Documentation/userspace-api/media/cec/cec-api.rst
+++ b/Documentation/userspace-api/media/cec/cec-api.rst
@@ -10,13 +10,8 @@ Part V - Consumer Electronics Control API
 This part describes the CEC: Consumer Electronics Control
 
 
-.. only:: html
-
-   .. class:: toc-title
-
-        Table of Contents
-
 .. toctree::
+    :caption: Table of Contents
     :maxdepth: 5
     :numbered:
 
diff --git a/Documentation/userspace-api/media/drivers/index.rst b/Documentation/userspace-api/media/drivers/index.rst
index 6708d649afd7..d4338dc506dd 100644
--- a/Documentation/userspace-api/media/drivers/index.rst
+++ b/Documentation/userspace-api/media/drivers/index.rst
@@ -21,13 +21,8 @@ more details.
 
 For more details see the file COPYING in the source distribution of Linux.
 
-.. only:: html
-
-   .. class:: toc-title
-
-        Table of Contents
-
 .. toctree::
+	:caption: Table of Contents
 	:maxdepth: 5
 	:numbered:
 
diff --git a/Documentation/userspace-api/media/dvb/dvbapi.rst b/Documentation/userspace-api/media/dvb/dvbapi.rst
index 1dda69343f34..4ac0c1bc54ca 100644
--- a/Documentation/userspace-api/media/dvb/dvbapi.rst
+++ b/Documentation/userspace-api/media/dvb/dvbapi.rst
@@ -27,13 +27,8 @@ Part II - Digital TV API
 
 **Version 5.10**
 
-.. only:: html
-
-   .. class:: toc-title
-
-        Table of Contents
-
 .. toctree::
+    :caption: Table of Contents
     :maxdepth: 5
     :numbered:
 
diff --git a/Documentation/userspace-api/media/index.rst b/Documentation/userspace-api/media/index.rst
index d839904be085..337ef6c7c47f 100644
--- a/Documentation/userspace-api/media/index.rst
+++ b/Documentation/userspace-api/media/index.rst
@@ -21,13 +21,8 @@ Documentation/driver-api/media/index.rst
     media devices;
 
 
-.. only:: html
-
-   .. class:: toc-title
-
-        Table of Contents
-
 .. toctree::
+    :caption: Table of Contents
     :maxdepth: 1
 
     intro
diff --git a/Documentation/userspace-api/media/mediactl/media-controller.rst b/Documentation/userspace-api/media/mediactl/media-controller.rst
index 508dd693bf6c..73a87f82f92d 100644
--- a/Documentation/userspace-api/media/mediactl/media-controller.rst
+++ b/Documentation/userspace-api/media/mediactl/media-controller.rst
@@ -7,13 +7,8 @@
 Part IV - Media Controller API
 ##############################
 
-.. only:: html
-
-   .. class:: toc-title
-
-        Table of Contents
-
 .. toctree::
+    :caption: Table of Contents
     :maxdepth: 5
     :numbered:
 
diff --git a/Documentation/userspace-api/media/rc/remote_controllers.rst b/Documentation/userspace-api/media/rc/remote_controllers.rst
index f89291838637..483f9ae92a90 100644
--- a/Documentation/userspace-api/media/rc/remote_controllers.rst
+++ b/Documentation/userspace-api/media/rc/remote_controllers.rst
@@ -7,13 +7,8 @@
 Part III - Remote Controller API
 ################################
 
-.. only:: html
-
-   .. class:: toc-title
-
-        Table of Contents
-
 .. toctree::
+    :caption: Table of Contents
     :maxdepth: 5
     :numbered:
 
diff --git a/Documentation/userspace-api/media/v4l/v4l2.rst b/Documentation/userspace-api/media/v4l/v4l2.rst
index ad7a2bf0cf26..cf8ae56a008c 100644
--- a/Documentation/userspace-api/media/v4l/v4l2.rst
+++ b/Documentation/userspace-api/media/v4l/v4l2.rst
@@ -11,13 +11,8 @@ This part describes the Video for Linux API version 2 (V4L2 API) specification.
 
 **Revision 4.5**
 
-.. only:: html
-
-   .. class:: toc-title
-
-        Table of Contents
-
 .. toctree::
+    :caption: Table of Contents
     :numbered:
     :maxdepth: 5
 
-- 
2.34.1

[PATCH RFC 10/11] docs: use toctree :caption: and move introduction

[Vegard Nossum]

The canonical way to add a heading to the ToC is to use :caption:.
Do that.

Let's also move the introduction to the top of the document to be
consistent with most other documents.

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Federico Vaga <federico.vaga@vaga.pv.it>
Cc: Alex Shi <alexs@kernel.org>
Cc: Yanteng Si <siyanteng@loongson.cn>
Cc: Hu Haowen <src.res.211@gmail.com>
Cc: workflows@vger.kernel.org
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
---
 Documentation/process/development-process.rst | 19 +++++++++----------
 .../it_IT/process/development-process.rst     | 19 +++++++++----------
 .../zh_CN/process/development-process.rst     |  5 ++---
 .../zh_TW/process/development-process.rst     |  5 ++---
 4 files changed, 22 insertions(+), 26 deletions(-)

diff --git a/Documentation/process/development-process.rst b/Documentation/process/development-process.rst
index 61c627e41ba8..e34d7da58b7f 100644
--- a/Documentation/process/development-process.rst
+++ b/Documentation/process/development-process.rst
@@ -3,9 +3,17 @@
 A guide to the Kernel Development Process
 =========================================
 
-Contents:
+The purpose of this document is to help developers (and their managers)
+work with the development community with a minimum of frustration.  It is
+an attempt to document how this community works in a way which is
+accessible to those who are not intimately familiar with Linux kernel
+development (or, indeed, free software development in general).  While
+there is some technical material here, this is very much a process-oriented
+discussion which does not require a deep knowledge of kernel programming to
+understand.
 
 .. toctree::
+   :caption: Contents
    :numbered:
    :maxdepth: 2
 
@@ -17,12 +25,3 @@ Contents:
    6.Followthrough
    7.AdvancedTopics
    8.Conclusion
-
-The purpose of this document is to help developers (and their managers)
-work with the development community with a minimum of frustration.  It is
-an attempt to document how this community works in a way which is
-accessible to those who are not intimately familiar with Linux kernel
-development (or, indeed, free software development in general).  While
-there is some technical material here, this is very much a process-oriented
-discussion which does not require a deep knowledge of kernel programming to
-understand.
diff --git a/Documentation/translations/it_IT/process/development-process.rst b/Documentation/translations/it_IT/process/development-process.rst
index f1a6eca30824..20e77c9816a1 100644
--- a/Documentation/translations/it_IT/process/development-process.rst
+++ b/Documentation/translations/it_IT/process/development-process.rst
@@ -8,9 +8,17 @@
 Una guida al processo di sviluppo del Kernel
 ============================================
 
-Contenuti:
+Lo scopo di questo documento è quello di aiutare gli sviluppatori (ed i loro
+supervisori) a lavorare con la communità di sviluppo con il minimo sforzo. È
+un tentativo di documentare il funzionamento di questa communità in modo che
+sia accessibile anche a coloro che non hanno famigliarità con lo sviluppo del
+Kernel Linux (o, anzi, con lo sviluppo di software libero in generale).  Benchè
+qui sia presente del materiale tecnico, questa è una discussione rivolta in
+particolare al procedimento, e quindi per essere compreso non richiede una
+conoscenza approfondità sullo sviluppo del kernel.
 
 .. toctree::
+   :caption: Contenuti
    :numbered:
    :maxdepth: 2
 
@@ -22,12 +30,3 @@ Contenuti:
    6.Followthrough
    7.AdvancedTopics
    8.Conclusion
-
-Lo scopo di questo documento è quello di aiutare gli sviluppatori (ed i loro
-supervisori) a lavorare con la communità di sviluppo con il minimo sforzo. È
-un tentativo di documentare il funzionamento di questa communità in modo che
-sia accessibile anche a coloro che non hanno famigliarità con lo sviluppo del
-Kernel Linux (o, anzi, con lo sviluppo di software libero in generale).  Benchè
-qui sia presente del materiale tecnico, questa è una discussione rivolta in
-particolare al procedimento, e quindi per essere compreso non richiede una
-conoscenza approfondità sullo sviluppo del kernel.
diff --git a/Documentation/translations/zh_CN/process/development-process.rst b/Documentation/translations/zh_CN/process/development-process.rst
index 30cffe66c075..c10d8e2e21eb 100644
--- a/Documentation/translations/zh_CN/process/development-process.rst
+++ b/Documentation/translations/zh_CN/process/development-process.rst
@@ -8,9 +8,10 @@
 内核开发过程指南
 ================
 
-内容:
+本文档的目的是帮助开发人员（及其经理）以最小的挫折感与开发社区合作。它试图记录这个社区如何以一种不熟悉Linux内核开发（或者实际上是自由软件开发）的人可以访问的方式工作。虽然这里有一些技术资料，但这是一个面向过程的讨论，不需要深入了解内核编程就可以理解。
 
 .. toctree::
+   :caption: 内容
    :numbered:
    :maxdepth: 2
 
@@ -22,5 +23,3 @@
    6.Followthrough
    7.AdvancedTopics
    8.Conclusion
-
-本文档的目的是帮助开发人员（及其经理）以最小的挫折感与开发社区合作。它试图记录这个社区如何以一种不熟悉Linux内核开发（或者实际上是自由软件开发）的人可以访问的方式工作。虽然这里有一些技术资料，但这是一个面向过程的讨论，不需要深入了解内核编程就可以理解。
diff --git a/Documentation/translations/zh_TW/process/development-process.rst b/Documentation/translations/zh_TW/process/development-process.rst
index f4cf5c2bbc82..c4db0e3e72ce 100644
--- a/Documentation/translations/zh_TW/process/development-process.rst
+++ b/Documentation/translations/zh_TW/process/development-process.rst
@@ -11,9 +11,10 @@
 內核開發過程指南
 ================
 
-內容:
+本文檔的目的是幫助開發人員（及其經理）以最小的挫折感與開發社區合作。它試圖記錄這個社區如何以一種不熟悉Linux內核開發（或者實際上是自由軟體開發）的人可以訪問的方式工作。雖然這裡有一些技術資料，但這是一個面向過程的討論，不需要深入了解內核編程就可以理解。
 
 .. toctree::
+   :caption: 內容
    :numbered:
    :maxdepth: 2
 
@@ -26,5 +27,3 @@
    7.AdvancedTopics
    8.Conclusion
 
-本文檔的目的是幫助開發人員（及其經理）以最小的挫折感與開發社區合作。它試圖記錄這個社區如何以一種不熟悉Linux內核開發（或者實際上是自由軟體開發）的人可以訪問的方式工作。雖然這裡有一些技術資料，但這是一個面向過程的討論，不需要深入了解內核編程就可以理解。
-
-- 
2.34.1

[PATCH RFC 11/11] docs: remove .toc-title class

[Vegard Nossum]

The "toc-title" class was introduced in commit ef88f10eb877
("[media] doc-rst: backward compatibility with older Sphinx versions")
as a workaround for Sphinx versions older than 1.4.x. However, these
old versions have been deprecated since commit 31abfdda6527
("docs: Deprecate use of Sphinx < 2.4.x").

Having now changed all the toc-title users to use the :caption:
attribute, we can also remove the custom style.

Note that the toc-title class is separate from the "kernel-toc"
logic that was introduced in commit c404f5d4f099 ("docs: Add more
information to the HTML sidebar").

Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
---
 Documentation/sphinx-static/theme_overrides.css | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css
index f6f2b941a5d6..79000b26e64e 100644
--- a/Documentation/sphinx-static/theme_overrides.css
+++ b/Documentation/sphinx-static/theme_overrides.css
@@ -81,11 +81,6 @@ div[class^="highlight"] pre {
      *   - hide the permalink symbol as long as link is not hovered
      */
 
-    .toc-title {
-        font-size: 150%;
-	font-weight: bold;
-    }
-
     caption, .wy-table caption, .rst-content table.field-list caption {
         font-size: 100%;
     }
-- 
2.34.1

Re: [PATCH RFC 00/11] use toctree :caption: for ToC headings

[Jani Nikula]

On Fri, 27 Oct 2023, Vegard Nossum <vegard.nossum@oracle.com> wrote:
> Hi,
>
> This patch series replaces some instances of 'class:: toc-title' with
> toctree's :caption: attribute, see the last patch in the series for
> some more rationale/explanation.
>
> There are some dependencies here: the first patch is necessary for the
> headings in following patches to be styled correctly with the alabaster
> theme (rtd_sphinx already has it), and the last patch depends on most
> of the previous patches to not use the old .toc-title class anymore.
>
> Assuming people agree with the general direction, I thought maybe the
> easiest thing would be to collect maintainer acks in this round and
> then for me to resubmit everything to the documentation tree/maintainer
> in one go.

Patch 1 is a matter of taste, I guess. I'll leave it to Jon.

Everything else LGTM.

For the benefit of others, the toctree directive gained the "caption"
option in Sphinx 1.3 [1].

BR,
Jani.


[1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html


>
>
> Vegard
>
> ---
>
> Vegard Nossum (11):
>   docs: style toctree captions as headings
>   doc: userspace-api: properly format ToC headings
>   media: admin-guide: properly format ToC heading
>   crypto: doc: properly format ToC headings
>   Documentation: dev-tools: properly format ToC headingss
>   docs: driver-api: properly format ToC headings
>   input: docs: properly format ToC headings
>   doc: misc-device: properly format ToC heading
>   media: doc: properly format ToC headings
>   docs: use toctree :caption: and move introduction
>   docs: remove .toc-title class
>
>  Documentation/admin-guide/media/index.rst     | 10 +---------
>  Documentation/crypto/api.rst                  |  5 +----
>  Documentation/crypto/index.rst                |  5 +----
>  Documentation/dev-tools/index.rst             |  5 +----
>  Documentation/driver-api/index.rst            |  5 +----
>  Documentation/driver-api/media/index.rst      |  7 +------
>  Documentation/driver-api/mei/index.rst        |  7 +------
>  Documentation/driver-api/pci/index.rst        |  5 +----
>  Documentation/input/input_kapi.rst            |  5 +----
>  Documentation/input/input_uapi.rst            |  5 +----
>  Documentation/input/joydev/index.rst          |  5 +----
>  Documentation/misc-devices/index.rst          |  5 +----
>  Documentation/process/development-process.rst | 19 +++++++++----------
>  Documentation/sphinx-static/custom.css        |  3 +++
>  .../sphinx-static/theme_overrides.css         |  5 -----
>  .../it_IT/process/development-process.rst     | 19 +++++++++----------
>  .../translations/zh_CN/dev-tools/index.rst    |  5 +----
>  .../zh_CN/driver-api/gpio/index.rst           |  3 +--
>  .../translations/zh_CN/driver-api/index.rst   |  5 +----
>  .../zh_CN/process/development-process.rst     |  5 ++---
>  .../zh_CN/userspace-api/index.rst             |  5 +----
>  .../zh_TW/process/development-process.rst     |  5 ++---
>  Documentation/userspace-api/index.rst         |  5 +----
>  .../userspace-api/media/cec/cec-api.rst       |  7 +------
>  .../userspace-api/media/drivers/index.rst     |  7 +------
>  .../userspace-api/media/dvb/dvbapi.rst        |  7 +------
>  Documentation/userspace-api/media/index.rst   |  7 +------
>  .../media/mediactl/media-controller.rst       |  7 +------
>  .../media/rc/remote_controllers.rst           |  7 +------
>  .../userspace-api/media/v4l/v4l2.rst          |  7 +------
>  30 files changed, 49 insertions(+), 148 deletions(-)

-- 
Jani Nikula, Intel

Re: [PATCH RFC 00/11] use toctree :caption: for ToC headings

[Jonathan Corbet]

Vegard Nossum <vegard.nossum@oracle.com> writes:

> Hi,
>
> This patch series replaces some instances of 'class:: toc-title' with
> toctree's :caption: attribute, see the last patch in the series for
> some more rationale/explanation.
>
> There are some dependencies here: the first patch is necessary for the
> headings in following patches to be styled correctly with the alabaster
> theme (rtd_sphinx already has it), and the last patch depends on most
> of the previous patches to not use the old .toc-title class anymore.
>
> Assuming people agree with the general direction, I thought maybe the
> easiest thing would be to collect maintainer acks in this round and
> then for me to resubmit everything to the documentation tree/maintainer
> in one go.

Easiest thing seems to be for me to just apply it, so I've done that.
It would have been a bit easier if you'd worked against a recent
docs-next, but so it goes...

Thanks,

jon