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
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 <[email protected]>
Cc: Jonathan Corbet <[email protected]>
Signed-off-by: Vegard Nossum <[email protected]>
---
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
"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 <[email protected]>
Cc: Julien Panis <[email protected]>
Signed-off-by: Vegard Nossum <[email protected]>
---
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
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 <[email protected]>
Cc: Mauro Carvalho Chehab <[email protected]>
Cc: Federico Vaga <[email protected]>
Cc: Alex Shi <[email protected]>
Cc: Yanteng Si <[email protected]>
Cc: Hu Haowen <[email protected]>
Cc: [email protected]
Signed-off-by: Vegard Nossum <[email protected]>
---
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
On Fri, 27 Oct 2023, Vegard Nossum <[email protected]> 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
Vegard Nossum <[email protected]> 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