mbox series

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

Message ID 20231027081830.195056-1-vegard.nossum@oracle.com
Headers
Series use toctree :caption: for ToC headings |

Message

Vegard Nossum Oct. 27, 2023, 8:18 a.m. UTC 
  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(-)

Comments

Jani Nikula Oct. 27, 2023, 8:32 a.m. UTC | #1 
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(-)
Jonathan Corbet Nov. 17, 2023, 8:09 p.m. UTC | #2 
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