* [PATCH 0/4] Documentation: clean up subproject index boilerplate
@ 2025-11-12 11:56 Jani Nikula
2025-11-12 11:56 ` [PATCH 1/4] Documentation: remove subproject index links deep in the structure Jani Nikula
` (5 more replies)
0 siblings, 6 replies; 17+ messages in thread
From: Jani Nikula @ 2025-11-12 11:56 UTC (permalink / raw)
To: linux-doc; +Cc: jani.nikula
Only very lightly tested.
Jani Nikula (4):
Documentation: remove subproject index links deep in the structure
Documentation: streamline subproject index link in translations
Documentation: include the boilerplate for SPHINXDIRS index link
Documentation: use a source-read extension to include the index
boilerplate
Documentation/RCU/index.rst | 7 -------
Documentation/accel/index.rst | 7 -------
Documentation/admin-guide/aoe/index.rst | 7 -------
Documentation/admin-guide/auxdisplay/index.rst | 7 -------
Documentation/admin-guide/cgroup-v1/index.rst | 7 -------
Documentation/admin-guide/cifs/index.rst | 7 -------
Documentation/admin-guide/device-mapper/index.rst | 7 -------
Documentation/admin-guide/gpio/index.rst | 7 -------
Documentation/admin-guide/index.rst | 7 -------
Documentation/admin-guide/kdump/index.rst | 7 -------
Documentation/arch/arc/index.rst | 7 -------
Documentation/arch/arm/index.rst | 8 --------
Documentation/arch/arm64/index.rst | 7 -------
Documentation/arch/loongarch/index.rst | 7 -------
Documentation/arch/m68k/index.rst | 7 -------
Documentation/arch/mips/index.rst | 7 -------
Documentation/arch/openrisc/index.rst | 7 -------
Documentation/arch/parisc/index.rst | 7 -------
Documentation/arch/powerpc/index.rst | 7 -------
Documentation/arch/riscv/index.rst | 7 -------
Documentation/arch/s390/index.rst | 7 -------
Documentation/bpf/index.rst | 7 -------
Documentation/cdrom/index.rst | 7 -------
Documentation/conf.py | 8 +++++++-
Documentation/core-api/index.rst | 7 -------
Documentation/core-api/kho/index.rst | 2 --
Documentation/dev-tools/index.rst | 8 --------
Documentation/doc-guide/index.rst | 7 -------
Documentation/driver-api/80211/index.rst | 7 -------
Documentation/driver-api/coco/index.rst | 2 --
Documentation/driver-api/crypto/iaa/index.rst | 7 -------
Documentation/driver-api/crypto/index.rst | 7 -------
Documentation/driver-api/cxl/index.rst | 2 --
Documentation/driver-api/dmaengine/index.rst | 7 -------
Documentation/driver-api/driver-model/index.rst | 7 -------
Documentation/driver-api/early-userspace/index.rst | 7 -------
Documentation/driver-api/firmware/index.rst | 7 -------
Documentation/driver-api/index.rst | 7 -------
Documentation/driver-api/memory-devices/index.rst | 7 -------
Documentation/driver-api/pci/index.rst | 7 -------
Documentation/driver-api/phy/index.rst | 8 --------
Documentation/driver-api/pm/index.rst | 7 -------
Documentation/driver-api/serial/index.rst | 7 -------
Documentation/driver-api/soundwire/index.rst | 7 -------
.../driver-api/surface_aggregator/clients/index.rst | 7 -------
Documentation/driver-api/surface_aggregator/index.rst | 7 -------
Documentation/driver-api/usb/index.rst | 7 -------
Documentation/driver-api/xilinx/index.rst | 7 -------
Documentation/fault-injection/index.rst | 7 -------
Documentation/fb/index.rst | 7 -------
Documentation/fpga/index.rst | 7 -------
Documentation/gpu/drivers.rst | 7 -------
Documentation/gpu/index.rst | 7 -------
Documentation/hwmon/index.rst | 7 -------
Documentation/i2c/index.rst | 7 -------
Documentation/infiniband/index.rst | 7 -------
Documentation/input/devices/index.rst | 7 -------
Documentation/input/index.rst | 7 -------
Documentation/isdn/index.rst | 7 -------
Documentation/kbuild/index.rst | 7 -------
Documentation/livepatch/index.rst | 7 -------
Documentation/locking/index.rst | 7 -------
Documentation/mhi/index.rst | 7 -------
Documentation/netlabel/index.rst | 7 -------
Documentation/networking/device_drivers/atm/index.rst | 7 -------
Documentation/networking/device_drivers/can/index.rst | 7 -------
.../networking/device_drivers/cellular/index.rst | 7 -------
.../networking/device_drivers/ethernet/index.rst | 7 -------
.../device_drivers/ethernet/mellanox/mlx5/index.rst | 7 -------
Documentation/networking/device_drivers/fddi/index.rst | 7 -------
.../networking/device_drivers/hamradio/index.rst | 7 -------
Documentation/networking/device_drivers/index.rst | 7 -------
Documentation/networking/device_drivers/wifi/index.rst | 7 -------
Documentation/networking/device_drivers/wwan/index.rst | 7 -------
Documentation/networking/diagnostic/index.rst | 7 -------
Documentation/networking/index.rst | 7 -------
Documentation/pcmcia/index.rst | 7 -------
Documentation/peci/index.rst | 7 -------
Documentation/power/index.rst | 7 -------
Documentation/process/debugging/index.rst | 9 ---------
Documentation/process/index.rst | 7 -------
Documentation/rust/index.rst | 7 -------
Documentation/scheduler/index.rst | 7 -------
Documentation/sound/index.rst | 7 -------
Documentation/sphinx-includes/subproject-index.rst | 4 ++++
Documentation/spi/index.rst | 7 -------
Documentation/target/index.rst | 7 -------
Documentation/tee/index.rst | 7 -------
Documentation/timers/index.rst | 7 -------
Documentation/tools/index.rst | 7 -------
Documentation/tools/rtla/index.rst | 7 -------
Documentation/tools/rv/index.rst | 7 -------
Documentation/trace/index.rst | 7 -------
Documentation/translations/it_IT/RCU/index.rst | 7 -------
Documentation/translations/it_IT/core-api/index.rst | 7 -------
Documentation/translations/it_IT/doc-guide/index.rst | 7 -------
Documentation/translations/it_IT/i2c/index.rst | 7 -------
Documentation/translations/it_IT/index.rst | 7 +++++++
Documentation/translations/it_IT/locking/index.rst | 7 -------
Documentation/translations/it_IT/process/index.rst | 7 -------
Documentation/translations/zh_CN/admin-guide/index.rst | 7 -------
.../translations/zh_CN/arch/loongarch/index.rst | 7 -------
Documentation/translations/zh_CN/arch/mips/index.rst | 7 -------
Documentation/translations/zh_CN/arch/openrisc/index.rst | 8 --------
Documentation/translations/zh_CN/arch/parisc/index.rst | 7 -------
Documentation/translations/zh_CN/arch/riscv/index.rst | 8 --------
Documentation/translations/zh_CN/core-api/index.rst | 7 -------
Documentation/translations/zh_CN/doc-guide/index.rst | 7 -------
Documentation/translations/zh_CN/driver-api/index.rst | 7 -------
.../translations/zh_CN/driver-api/phy/index.rst | 7 -------
Documentation/translations/zh_CN/infiniband/index.rst | 9 ---------
Documentation/translations/zh_CN/kbuild/index.rst | 8 --------
Documentation/translations/zh_CN/locking/index.rst | 7 -------
Documentation/translations/zh_CN/networking/index.rst | 7 -------
Documentation/translations/zh_CN/peci/index.rst | 7 -------
Documentation/translations/zh_CN/power/index.rst | 7 -------
Documentation/translations/zh_CN/process/index.rst | 7 -------
Documentation/translations/zh_CN/rust/index.rst | 7 -------
Documentation/translations/zh_CN/scheduler/index.rst | 7 -------
Documentation/translations/zh_CN/sound/index.rst | 7 -------
Documentation/translations/zh_CN/userspace-api/index.rst | 7 -------
Documentation/translations/zh_CN/virt/index.rst | 7 -------
Documentation/translations/zh_TW/admin-guide/index.rst | 8 --------
.../translations/zh_TW/arch/loongarch/index.rst | 8 --------
Documentation/translations/zh_TW/arch/mips/index.rst | 8 --------
Documentation/translations/zh_TW/arch/openrisc/index.rst | 9 ---------
Documentation/translations/zh_TW/arch/parisc/index.rst | 8 --------
Documentation/translations/zh_TW/process/index.rst | 8 --------
Documentation/usb/index.rst | 7 -------
Documentation/userspace-api/gpio/index.rst | 7 -------
Documentation/userspace-api/index.rst | 7 -------
Documentation/virt/index.rst | 7 -------
Documentation/w1/index.rst | 7 -------
Documentation/watchdog/index.rst | 7 -------
Documentation/wmi/devices/index.rst | 7 -------
Documentation/wmi/index.rst | 8 --------
136 files changed, 18 insertions(+), 935 deletions(-)
create mode 100644 Documentation/sphinx-includes/subproject-index.rst
--
2.47.3
^ permalink raw reply [flat|nested] 17+ messages in thread
* [PATCH 1/4] Documentation: remove subproject index links deep in the structure
2025-11-12 11:56 [PATCH 0/4] Documentation: clean up subproject index boilerplate Jani Nikula
@ 2025-11-12 11:56 ` Jani Nikula
2025-11-12 13:27 ` Mauro Carvalho Chehab
2025-11-12 11:56 ` [PATCH 2/4] Documentation: streamline subproject index link in translations Jani Nikula
` (4 subsequent siblings)
5 siblings, 1 reply; 17+ messages in thread
From: Jani Nikula @ 2025-11-12 11:56 UTC (permalink / raw)
To: linux-doc
Cc: jani.nikula, Randy Dunlap, Mauro Carvalho Chehab, Jonathan Corbet
The idea of having
.. only:: subproject and html
Indices
=======
* :ref:`genindex`
in index.rst pages is to add the index link to the main page of the
subproject when doing SPHINXDIRS builds. There's no such need deeper in
the documentation structure, and we can safely get rid of them. In all
likelihood, it's just cargo culted and copy-pasted.
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
Documentation/admin-guide/aoe/index.rst | 7 -------
Documentation/admin-guide/auxdisplay/index.rst | 7 -------
Documentation/admin-guide/cgroup-v1/index.rst | 7 -------
Documentation/admin-guide/cifs/index.rst | 7 -------
Documentation/admin-guide/device-mapper/index.rst | 7 -------
Documentation/admin-guide/gpio/index.rst | 7 -------
Documentation/admin-guide/kdump/index.rst | 7 -------
Documentation/arch/arc/index.rst | 7 -------
Documentation/arch/arm/index.rst | 8 --------
Documentation/arch/arm64/index.rst | 7 -------
Documentation/arch/loongarch/index.rst | 7 -------
Documentation/arch/m68k/index.rst | 7 -------
Documentation/arch/mips/index.rst | 7 -------
Documentation/arch/openrisc/index.rst | 7 -------
Documentation/arch/parisc/index.rst | 7 -------
Documentation/arch/powerpc/index.rst | 7 -------
Documentation/arch/riscv/index.rst | 7 -------
Documentation/arch/s390/index.rst | 7 -------
Documentation/core-api/kho/index.rst | 2 --
Documentation/driver-api/80211/index.rst | 7 -------
Documentation/driver-api/coco/index.rst | 2 --
Documentation/driver-api/crypto/iaa/index.rst | 7 -------
Documentation/driver-api/crypto/index.rst | 7 -------
Documentation/driver-api/cxl/index.rst | 2 --
Documentation/driver-api/dmaengine/index.rst | 7 -------
Documentation/driver-api/driver-model/index.rst | 7 -------
Documentation/driver-api/early-userspace/index.rst | 7 -------
Documentation/driver-api/firmware/index.rst | 7 -------
Documentation/driver-api/memory-devices/index.rst | 7 -------
Documentation/driver-api/pci/index.rst | 7 -------
Documentation/driver-api/phy/index.rst | 8 --------
Documentation/driver-api/pm/index.rst | 7 -------
Documentation/driver-api/serial/index.rst | 7 -------
Documentation/driver-api/soundwire/index.rst | 7 -------
.../driver-api/surface_aggregator/clients/index.rst | 7 -------
Documentation/driver-api/surface_aggregator/index.rst | 7 -------
Documentation/driver-api/usb/index.rst | 7 -------
Documentation/driver-api/xilinx/index.rst | 7 -------
Documentation/input/devices/index.rst | 7 -------
Documentation/networking/device_drivers/atm/index.rst | 7 -------
Documentation/networking/device_drivers/can/index.rst | 7 -------
.../networking/device_drivers/cellular/index.rst | 7 -------
.../networking/device_drivers/ethernet/index.rst | 7 -------
.../device_drivers/ethernet/mellanox/mlx5/index.rst | 7 -------
Documentation/networking/device_drivers/fddi/index.rst | 7 -------
.../networking/device_drivers/hamradio/index.rst | 7 -------
Documentation/networking/device_drivers/index.rst | 7 -------
Documentation/networking/device_drivers/wifi/index.rst | 7 -------
Documentation/networking/device_drivers/wwan/index.rst | 7 -------
Documentation/networking/diagnostic/index.rst | 7 -------
Documentation/process/debugging/index.rst | 9 ---------
Documentation/tools/rtla/index.rst | 7 -------
Documentation/tools/rv/index.rst | 7 -------
.../translations/zh_CN/arch/loongarch/index.rst | 7 -------
Documentation/translations/zh_CN/arch/mips/index.rst | 7 -------
Documentation/translations/zh_CN/arch/openrisc/index.rst | 8 --------
Documentation/translations/zh_CN/arch/parisc/index.rst | 7 -------
Documentation/translations/zh_CN/arch/riscv/index.rst | 8 --------
.../translations/zh_CN/driver-api/phy/index.rst | 7 -------
.../translations/zh_TW/arch/loongarch/index.rst | 8 --------
Documentation/translations/zh_TW/arch/mips/index.rst | 8 --------
Documentation/translations/zh_TW/arch/openrisc/index.rst | 9 ---------
Documentation/translations/zh_TW/arch/parisc/index.rst | 8 --------
Documentation/userspace-api/gpio/index.rst | 7 -------
Documentation/wmi/devices/index.rst | 7 -------
65 files changed, 451 deletions(-)
diff --git a/Documentation/admin-guide/aoe/index.rst b/Documentation/admin-guide/aoe/index.rst
index d71c5df15922..564354bbce57 100644
--- a/Documentation/admin-guide/aoe/index.rst
+++ b/Documentation/admin-guide/aoe/index.rst
@@ -8,10 +8,3 @@ ATA over Ethernet (AoE)
aoe
todo
examples
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/admin-guide/auxdisplay/index.rst b/Documentation/admin-guide/auxdisplay/index.rst
index e466f0595248..31eae08255fd 100644
--- a/Documentation/admin-guide/auxdisplay/index.rst
+++ b/Documentation/admin-guide/auxdisplay/index.rst
@@ -7,10 +7,3 @@ Auxiliary Display Support
ks0108.rst
cfag12864b.rst
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/admin-guide/cgroup-v1/index.rst b/Documentation/admin-guide/cgroup-v1/index.rst
index 99fbc8a64ba9..14897a8d32b3 100644
--- a/Documentation/admin-guide/cgroup-v1/index.rst
+++ b/Documentation/admin-guide/cgroup-v1/index.rst
@@ -22,10 +22,3 @@ Control Groups version 1
net_prio
pids
rdma
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/admin-guide/cifs/index.rst b/Documentation/admin-guide/cifs/index.rst
index fad5268635f5..58ab58a71a82 100644
--- a/Documentation/admin-guide/cifs/index.rst
+++ b/Documentation/admin-guide/cifs/index.rst
@@ -12,10 +12,3 @@ CIFS
todo
changes
authors
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/admin-guide/device-mapper/index.rst b/Documentation/admin-guide/device-mapper/index.rst
index f1c1f4b824ba..030d854628ac 100644
--- a/Documentation/admin-guide/device-mapper/index.rst
+++ b/Documentation/admin-guide/device-mapper/index.rst
@@ -40,10 +40,3 @@ Device Mapper
verity
writecache
zero
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst
index 712f379731cb..082646851029 100644
--- a/Documentation/admin-guide/gpio/index.rst
+++ b/Documentation/admin-guide/gpio/index.rst
@@ -12,10 +12,3 @@ GPIO
gpio-sim
gpio-virtuser
Obsolete APIs <obsolete>
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/admin-guide/kdump/index.rst b/Documentation/admin-guide/kdump/index.rst
index 8e2ebd0383cd..cf5d7c868b74 100644
--- a/Documentation/admin-guide/kdump/index.rst
+++ b/Documentation/admin-guide/kdump/index.rst
@@ -11,10 +11,3 @@ information.
kdump
vmcoreinfo
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/arch/arc/index.rst b/Documentation/arch/arc/index.rst
index 7b098d4a5e3e..10bf8c2701bf 100644
--- a/Documentation/arch/arc/index.rst
+++ b/Documentation/arch/arc/index.rst
@@ -8,10 +8,3 @@ ARC architecture
arc
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/arch/arm/index.rst b/Documentation/arch/arm/index.rst
index fd43502ae924..afe17db294c4 100644
--- a/Documentation/arch/arm/index.rst
+++ b/Documentation/arch/arm/index.rst
@@ -75,11 +75,3 @@ SoC-specific documents
sti/overview
vfp/release-notes
-
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/arch/arm64/index.rst b/Documentation/arch/arm64/index.rst
index 6a012c98bdcd..af52edc8c0ac 100644
--- a/Documentation/arch/arm64/index.rst
+++ b/Documentation/arch/arm64/index.rst
@@ -33,10 +33,3 @@ ARM64 Architecture
tagged-pointers
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/arch/loongarch/index.rst b/Documentation/arch/loongarch/index.rst
index c779bfa00c05..df590b117240 100644
--- a/Documentation/arch/loongarch/index.rst
+++ b/Documentation/arch/loongarch/index.rst
@@ -13,10 +13,3 @@ LoongArch Architecture
irq-chip-model
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/arch/m68k/index.rst b/Documentation/arch/m68k/index.rst
index 0f890dbb5fe2..c334026e0ae1 100644
--- a/Documentation/arch/m68k/index.rst
+++ b/Documentation/arch/m68k/index.rst
@@ -11,10 +11,3 @@ m68k Architecture
buddha-driver
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/arch/mips/index.rst b/Documentation/arch/mips/index.rst
index 037f85a08fe3..703e195b933d 100644
--- a/Documentation/arch/mips/index.rst
+++ b/Documentation/arch/mips/index.rst
@@ -12,10 +12,3 @@ MIPS-specific Documentation
ingenic-tcu
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/arch/openrisc/index.rst b/Documentation/arch/openrisc/index.rst
index 6879f998b87a..79fe8b0c2c41 100644
--- a/Documentation/arch/openrisc/index.rst
+++ b/Documentation/arch/openrisc/index.rst
@@ -11,10 +11,3 @@ OpenRISC Architecture
todo
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/arch/parisc/index.rst b/Documentation/arch/parisc/index.rst
index 240685751825..15ccc787fd4f 100644
--- a/Documentation/arch/parisc/index.rst
+++ b/Documentation/arch/parisc/index.rst
@@ -11,10 +11,3 @@ PA-RISC Architecture
registers
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/arch/powerpc/index.rst b/Documentation/arch/powerpc/index.rst
index 1be2ee3f0361..40419bea8e10 100644
--- a/Documentation/arch/powerpc/index.rst
+++ b/Documentation/arch/powerpc/index.rst
@@ -40,10 +40,3 @@ powerpc
vpa-dtl
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/arch/riscv/index.rst b/Documentation/arch/riscv/index.rst
index eecf347ce849..830fde0c8aa3 100644
--- a/Documentation/arch/riscv/index.rst
+++ b/Documentation/arch/riscv/index.rst
@@ -16,10 +16,3 @@ RISC-V architecture
cmodx
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/arch/s390/index.rst b/Documentation/arch/s390/index.rst
index e75a6e5d2505..769434f0625b 100644
--- a/Documentation/arch/s390/index.rst
+++ b/Documentation/arch/s390/index.rst
@@ -22,10 +22,3 @@ s390 Architecture
text_files
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/core-api/kho/index.rst b/Documentation/core-api/kho/index.rst
index 0c63b0c5c143..51ea41c6a20d 100644
--- a/Documentation/core-api/kho/index.rst
+++ b/Documentation/core-api/kho/index.rst
@@ -9,5 +9,3 @@ Kexec Handover Subsystem
concepts
fdt
-
-.. only:: subproject and html
diff --git a/Documentation/driver-api/80211/index.rst b/Documentation/driver-api/80211/index.rst
index af210859d3e1..62305e9c3113 100644
--- a/Documentation/driver-api/80211/index.rst
+++ b/Documentation/driver-api/80211/index.rst
@@ -8,10 +8,3 @@ Linux 802.11 Driver Developer's Guide
cfg80211
mac80211
mac80211-advanced
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/driver-api/coco/index.rst b/Documentation/driver-api/coco/index.rst
index af9f08ca0cfd..783c8b033547 100644
--- a/Documentation/driver-api/coco/index.rst
+++ b/Documentation/driver-api/coco/index.rst
@@ -8,5 +8,3 @@ Confidential Computing
:maxdepth: 1
measurement-registers
-
-.. only:: subproject and html
diff --git a/Documentation/driver-api/crypto/iaa/index.rst b/Documentation/driver-api/crypto/iaa/index.rst
index aa6837e27264..463f7da569c5 100644
--- a/Documentation/driver-api/crypto/iaa/index.rst
+++ b/Documentation/driver-api/crypto/iaa/index.rst
@@ -11,10 +11,3 @@ API.
:maxdepth: 1
iaa-crypto
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/driver-api/crypto/index.rst b/Documentation/driver-api/crypto/index.rst
index fb9709b98bea..bba669014cb2 100644
--- a/Documentation/driver-api/crypto/index.rst
+++ b/Documentation/driver-api/crypto/index.rst
@@ -11,10 +11,3 @@ configuration.
:maxdepth: 1
iaa/index
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/driver-api/cxl/index.rst b/Documentation/driver-api/cxl/index.rst
index c1106a68b67c..ec8aae9ec0d4 100644
--- a/Documentation/driver-api/cxl/index.rst
+++ b/Documentation/driver-api/cxl/index.rst
@@ -50,5 +50,3 @@ that have impacts on each other. The docs here break up configurations steps.
allocation/page-allocator
allocation/reclaim
allocation/hugepages.rst
-
-.. only:: subproject and html
diff --git a/Documentation/driver-api/dmaengine/index.rst b/Documentation/driver-api/dmaengine/index.rst
index bdc45d8b4cfb..e74677c664ac 100644
--- a/Documentation/driver-api/dmaengine/index.rst
+++ b/Documentation/driver-api/dmaengine/index.rst
@@ -46,10 +46,3 @@ This book adds some notes about PXA DMA
:maxdepth: 1
pxa_dma
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/driver-api/driver-model/index.rst b/Documentation/driver-api/driver-model/index.rst
index 4831bdd92e5c..abeb4b36636b 100644
--- a/Documentation/driver-api/driver-model/index.rst
+++ b/Documentation/driver-api/driver-model/index.rst
@@ -14,10 +14,3 @@ Driver Model
overview
platform
porting
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/driver-api/early-userspace/index.rst b/Documentation/driver-api/early-userspace/index.rst
index 149c1822f06d..ff459471258f 100644
--- a/Documentation/driver-api/early-userspace/index.rst
+++ b/Documentation/driver-api/early-userspace/index.rst
@@ -9,10 +9,3 @@ Early Userspace
early_userspace_support
buffer-format
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/driver-api/firmware/index.rst b/Documentation/driver-api/firmware/index.rst
index 9d2c19dc8e36..86a3dd4bc3f8 100644
--- a/Documentation/driver-api/firmware/index.rst
+++ b/Documentation/driver-api/firmware/index.rst
@@ -10,10 +10,3 @@ Linux Firmware API
request_firmware
fw_upload
other_interfaces
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/driver-api/memory-devices/index.rst b/Documentation/driver-api/memory-devices/index.rst
index 28101458cda5..3b6308113611 100644
--- a/Documentation/driver-api/memory-devices/index.rst
+++ b/Documentation/driver-api/memory-devices/index.rst
@@ -9,10 +9,3 @@ Memory Controller drivers
ti-emif
ti-gpmc
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/driver-api/pci/index.rst b/Documentation/driver-api/pci/index.rst
index a38e475cdbe3..fd73bd44d5a9 100644
--- a/Documentation/driver-api/pci/index.rst
+++ b/Documentation/driver-api/pci/index.rst
@@ -10,10 +10,3 @@ The Linux PCI driver implementer's API guide
pci
p2pdma
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/driver-api/phy/index.rst b/Documentation/driver-api/phy/index.rst
index 69ba1216de72..579cfe3b7b82 100644
--- a/Documentation/driver-api/phy/index.rst
+++ b/Documentation/driver-api/phy/index.rst
@@ -8,11 +8,3 @@ Generic PHY Framework
phy
samsung-usb2
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
-
diff --git a/Documentation/driver-api/pm/index.rst b/Documentation/driver-api/pm/index.rst
index c2a9ef8d115c..4d6c32e32a72 100644
--- a/Documentation/driver-api/pm/index.rst
+++ b/Documentation/driver-api/pm/index.rst
@@ -10,10 +10,3 @@ CPU and Device Power Management
devices
notifiers
types
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/driver-api/serial/index.rst b/Documentation/driver-api/serial/index.rst
index 03a55b987a1d..610744df5e8d 100644
--- a/Documentation/driver-api/serial/index.rst
+++ b/Documentation/driver-api/serial/index.rst
@@ -18,10 +18,3 @@ Serial drivers
serial-iso7816
serial-rs485
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/driver-api/soundwire/index.rst b/Documentation/driver-api/soundwire/index.rst
index ef8d90dfbdde..f7abf4a95be7 100644
--- a/Documentation/driver-api/soundwire/index.rst
+++ b/Documentation/driver-api/soundwire/index.rst
@@ -11,10 +11,3 @@ SoundWire Documentation
locking
bra
bra_cadence
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/driver-api/surface_aggregator/clients/index.rst b/Documentation/driver-api/surface_aggregator/clients/index.rst
index 30160513afa5..c32313b8f3b7 100644
--- a/Documentation/driver-api/surface_aggregator/clients/index.rst
+++ b/Documentation/driver-api/surface_aggregator/clients/index.rst
@@ -14,10 +14,3 @@ on how to write client drivers.
cdev
dtx
san
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/driver-api/surface_aggregator/index.rst b/Documentation/driver-api/surface_aggregator/index.rst
index 6f3e1094904d..f0128fe59a32 100644
--- a/Documentation/driver-api/surface_aggregator/index.rst
+++ b/Documentation/driver-api/surface_aggregator/index.rst
@@ -12,10 +12,3 @@ Surface System Aggregator Module (SSAM)
clients/index
ssh
internal
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst
index fcb24d0500d9..a32819963b99 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -22,10 +22,3 @@ Linux USB API
typec
typec_bus
usb3-debug-port
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/driver-api/xilinx/index.rst b/Documentation/driver-api/xilinx/index.rst
index 13f7589ed442..c95bda55da6f 100644
--- a/Documentation/driver-api/xilinx/index.rst
+++ b/Documentation/driver-api/xilinx/index.rst
@@ -7,10 +7,3 @@ Xilinx FPGA
:maxdepth: 1
eemi
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/input/devices/index.rst b/Documentation/input/devices/index.rst
index 95a453782bad..6de4365ad288 100644
--- a/Documentation/input/devices/index.rst
+++ b/Documentation/input/devices/index.rst
@@ -10,10 +10,3 @@ Linux kernel, their protocols, and driver details.
:glob:
*
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/networking/device_drivers/atm/index.rst b/Documentation/networking/device_drivers/atm/index.rst
index 7b593f031a60..724552ca0be4 100644
--- a/Documentation/networking/device_drivers/atm/index.rst
+++ b/Documentation/networking/device_drivers/atm/index.rst
@@ -11,10 +11,3 @@ Contents:
cxacru
fore200e
iphase
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/networking/device_drivers/can/index.rst b/Documentation/networking/device_drivers/can/index.rst
index 6a8a4f74fa26..af4369989522 100644
--- a/Documentation/networking/device_drivers/can/index.rst
+++ b/Documentation/networking/device_drivers/can/index.rst
@@ -13,10 +13,3 @@ Contents:
can327
ctu/ctucanfd-driver
freescale/flexcan
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/networking/device_drivers/cellular/index.rst b/Documentation/networking/device_drivers/cellular/index.rst
index fc1812d3fc70..9690c3ba08ef 100644
--- a/Documentation/networking/device_drivers/cellular/index.rst
+++ b/Documentation/networking/device_drivers/cellular/index.rst
@@ -9,10 +9,3 @@ Contents:
:maxdepth: 2
qualcomm/rmnet
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/networking/device_drivers/ethernet/index.rst b/Documentation/networking/device_drivers/ethernet/index.rst
index 7cfcd183054f..76864a5f2db4 100644
--- a/Documentation/networking/device_drivers/ethernet/index.rst
+++ b/Documentation/networking/device_drivers/ethernet/index.rst
@@ -63,10 +63,3 @@ Contents:
wangxun/txgbevf
wangxun/ngbe
wangxun/ngbevf
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/index.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/index.rst
index 581a91caa579..56f3966de3f0 100644
--- a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/index.rst
+++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/index.rst
@@ -16,10 +16,3 @@ Contents:
switchdev
tracepoints
counters
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/networking/device_drivers/fddi/index.rst b/Documentation/networking/device_drivers/fddi/index.rst
index 0b75294e6c8b..c7cf2347e215 100644
--- a/Documentation/networking/device_drivers/fddi/index.rst
+++ b/Documentation/networking/device_drivers/fddi/index.rst
@@ -10,10 +10,3 @@ Contents:
defza
skfp
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/networking/device_drivers/hamradio/index.rst b/Documentation/networking/device_drivers/hamradio/index.rst
index 7e731732057b..6af481c5b020 100644
--- a/Documentation/networking/device_drivers/hamradio/index.rst
+++ b/Documentation/networking/device_drivers/hamradio/index.rst
@@ -10,10 +10,3 @@ Contents:
baycom
z8530drv
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst
index a254af25b7ef..1df51c9f7827 100644
--- a/Documentation/networking/device_drivers/index.rst
+++ b/Documentation/networking/device_drivers/index.rst
@@ -16,10 +16,3 @@ Contents:
hamradio/index
wifi/index
wwan/index
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/networking/device_drivers/wifi/index.rst b/Documentation/networking/device_drivers/wifi/index.rst
index fb394f5de4a9..29ba9ea64b25 100644
--- a/Documentation/networking/device_drivers/wifi/index.rst
+++ b/Documentation/networking/device_drivers/wifi/index.rst
@@ -10,10 +10,3 @@ Contents:
intel/ipw2100
intel/ipw2200
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/networking/device_drivers/wwan/index.rst b/Documentation/networking/device_drivers/wwan/index.rst
index 370d8264d5dc..b768ae89f723 100644
--- a/Documentation/networking/device_drivers/wwan/index.rst
+++ b/Documentation/networking/device_drivers/wwan/index.rst
@@ -10,10 +10,3 @@ Contents:
iosm
t7xx
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/networking/diagnostic/index.rst b/Documentation/networking/diagnostic/index.rst
index 86488aa46b48..592263a2713a 100644
--- a/Documentation/networking/diagnostic/index.rst
+++ b/Documentation/networking/diagnostic/index.rst
@@ -8,10 +8,3 @@ Networking Diagnostics
:maxdepth: 2
twisted_pair_layer1_diagnostics.rst
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/process/debugging/index.rst b/Documentation/process/debugging/index.rst
index 387d33d16f5e..357243e184e1 100644
--- a/Documentation/process/debugging/index.rst
+++ b/Documentation/process/debugging/index.rst
@@ -15,8 +15,6 @@ general guides
kgdb
userspace_debugging_guide
-.. only:: subproject and html
-
subsystem specific guides
-------------------------
@@ -25,13 +23,6 @@ subsystem specific guides
media_specific_debugging_guide
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
-
General debugging advice
========================
diff --git a/Documentation/tools/rtla/index.rst b/Documentation/tools/rtla/index.rst
index 05d2652e4072..7664d6d0cb27 100644
--- a/Documentation/tools/rtla/index.rst
+++ b/Documentation/tools/rtla/index.rst
@@ -18,10 +18,3 @@ behavior on specific hardware.
rtla-timerlat-hist
rtla-timerlat-top
rtla-hwnoise
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/tools/rv/index.rst b/Documentation/tools/rv/index.rst
index 64ba2efe2e85..fd42b0017d07 100644
--- a/Documentation/tools/rv/index.rst
+++ b/Documentation/tools/rv/index.rst
@@ -16,10 +16,3 @@ Runtime verification (rv) tool
rv-mon-wip
rv-mon-wwnr
rv-mon-sched
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/arch/loongarch/index.rst b/Documentation/translations/zh_CN/arch/loongarch/index.rst
index 4bd24f5ffed1..78633c82809e 100644
--- a/Documentation/translations/zh_CN/arch/loongarch/index.rst
+++ b/Documentation/translations/zh_CN/arch/loongarch/index.rst
@@ -18,10 +18,3 @@ LoongArch体系结构
irq-chip-model
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/arch/mips/index.rst b/Documentation/translations/zh_CN/arch/mips/index.rst
index 2a34217119ea..079d8979ba8d 100644
--- a/Documentation/translations/zh_CN/arch/mips/index.rst
+++ b/Documentation/translations/zh_CN/arch/mips/index.rst
@@ -20,10 +20,3 @@ MIPS特性文档
ingenic-tcu
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/arch/openrisc/index.rst b/Documentation/translations/zh_CN/arch/openrisc/index.rst
index da21f8ab894b..bdecc3bf88d7 100644
--- a/Documentation/translations/zh_CN/arch/openrisc/index.rst
+++ b/Documentation/translations/zh_CN/arch/openrisc/index.rst
@@ -22,11 +22,3 @@ OpenRISC 体系架构
Todolist:
features
-
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/arch/parisc/index.rst b/Documentation/translations/zh_CN/arch/parisc/index.rst
index 9f69283bd1c9..cba3a5d2e74c 100644
--- a/Documentation/translations/zh_CN/arch/parisc/index.rst
+++ b/Documentation/translations/zh_CN/arch/parisc/index.rst
@@ -22,10 +22,3 @@ PA-RISC体系架构
Todolist:
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/arch/riscv/index.rst b/Documentation/translations/zh_CN/arch/riscv/index.rst
index 96573459105e..eb36009874e5 100644
--- a/Documentation/translations/zh_CN/arch/riscv/index.rst
+++ b/Documentation/translations/zh_CN/arch/riscv/index.rst
@@ -21,11 +21,3 @@ RISC-V 体系结构
boot-image-header
vm-layout
patch-acceptance
-
-
-.. only:: subproject and html
-
- 目录
- ====
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/driver-api/phy/index.rst b/Documentation/translations/zh_CN/driver-api/phy/index.rst
index 2cdce17b74a9..d6e4f729fac0 100644
--- a/Documentation/translations/zh_CN/driver-api/phy/index.rst
+++ b/Documentation/translations/zh_CN/driver-api/phy/index.rst
@@ -11,10 +11,3 @@ PHY 通用框架
Todolist:
* samsung-usb2
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_TW/arch/loongarch/index.rst b/Documentation/translations/zh_TW/arch/loongarch/index.rst
index 7281e050fe1c..ee3e01d99891 100644
--- a/Documentation/translations/zh_TW/arch/loongarch/index.rst
+++ b/Documentation/translations/zh_TW/arch/loongarch/index.rst
@@ -18,11 +18,3 @@ LoongArch體系結構
irq-chip-model
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
-
diff --git a/Documentation/translations/zh_TW/arch/mips/index.rst b/Documentation/translations/zh_TW/arch/mips/index.rst
index 4b7d28806489..ee0cf95e69ff 100644
--- a/Documentation/translations/zh_TW/arch/mips/index.rst
+++ b/Documentation/translations/zh_TW/arch/mips/index.rst
@@ -20,11 +20,3 @@ MIPS特性文檔
ingenic-tcu
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
-
diff --git a/Documentation/translations/zh_TW/arch/openrisc/index.rst b/Documentation/translations/zh_TW/arch/openrisc/index.rst
index 7585960783fc..f830fb830e38 100644
--- a/Documentation/translations/zh_TW/arch/openrisc/index.rst
+++ b/Documentation/translations/zh_TW/arch/openrisc/index.rst
@@ -22,12 +22,3 @@ OpenRISC 體系架構
Todolist:
features
-
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
-
diff --git a/Documentation/translations/zh_TW/arch/parisc/index.rst b/Documentation/translations/zh_TW/arch/parisc/index.rst
index 35941bf68c88..8f75e2439738 100644
--- a/Documentation/translations/zh_TW/arch/parisc/index.rst
+++ b/Documentation/translations/zh_TW/arch/parisc/index.rst
@@ -22,11 +22,3 @@ PA-RISC體系架構
Todolist:
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
-
diff --git a/Documentation/userspace-api/gpio/index.rst b/Documentation/userspace-api/gpio/index.rst
index f258de4ef370..ac9c6ff9875c 100644
--- a/Documentation/userspace-api/gpio/index.rst
+++ b/Documentation/userspace-api/gpio/index.rst
@@ -9,10 +9,3 @@ GPIO
Character Device Userspace API <chardev>
Obsolete Userspace APIs <obsolete>
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/wmi/devices/index.rst b/Documentation/wmi/devices/index.rst
index c08735a9d7df..b0a9b4229add 100644
--- a/Documentation/wmi/devices/index.rst
+++ b/Documentation/wmi/devices/index.rst
@@ -13,10 +13,3 @@ the Linux kernel, their protocols and driver details.
:glob:
*
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
--
2.47.3
^ permalink raw reply related [flat|nested] 17+ messages in thread
* [PATCH 2/4] Documentation: streamline subproject index link in translations
2025-11-12 11:56 [PATCH 0/4] Documentation: clean up subproject index boilerplate Jani Nikula
2025-11-12 11:56 ` [PATCH 1/4] Documentation: remove subproject index links deep in the structure Jani Nikula
@ 2025-11-12 11:56 ` Jani Nikula
2025-11-12 11:56 ` [PATCH 3/4] Documentation: include the boilerplate for SPHINXDIRS index link Jani Nikula
` (3 subsequent siblings)
5 siblings, 0 replies; 17+ messages in thread
From: Jani Nikula @ 2025-11-12 11:56 UTC (permalink / raw)
To: linux-doc
Cc: jani.nikula, Randy Dunlap, Mauro Carvalho Chehab, Jonathan Corbet
Remove index links deep inside the translations structure. We'll want:
- Top level index link at the translations index.rst when doing
SPHINXDIRS builds. Add this.
- Language specific top level index links when doing HTML builds. This
should not depend on SPHINXDIRS. Most translations have it already,
add one for Italian, the remaining ones I'm not capable of adding.
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
Documentation/translations/index.rst | 7 +++++++
Documentation/translations/it_IT/RCU/index.rst | 7 -------
Documentation/translations/it_IT/core-api/index.rst | 7 -------
Documentation/translations/it_IT/doc-guide/index.rst | 7 -------
Documentation/translations/it_IT/i2c/index.rst | 7 -------
Documentation/translations/it_IT/index.rst | 7 +++++++
Documentation/translations/it_IT/locking/index.rst | 7 -------
Documentation/translations/it_IT/process/index.rst | 7 -------
Documentation/translations/zh_CN/admin-guide/index.rst | 7 -------
Documentation/translations/zh_CN/core-api/index.rst | 7 -------
Documentation/translations/zh_CN/doc-guide/index.rst | 7 -------
Documentation/translations/zh_CN/driver-api/index.rst | 7 -------
Documentation/translations/zh_CN/infiniband/index.rst | 9 ---------
Documentation/translations/zh_CN/kbuild/index.rst | 8 --------
Documentation/translations/zh_CN/locking/index.rst | 7 -------
Documentation/translations/zh_CN/networking/index.rst | 7 -------
Documentation/translations/zh_CN/peci/index.rst | 7 -------
Documentation/translations/zh_CN/power/index.rst | 7 -------
Documentation/translations/zh_CN/process/index.rst | 7 -------
Documentation/translations/zh_CN/rust/index.rst | 7 -------
Documentation/translations/zh_CN/scheduler/index.rst | 7 -------
Documentation/translations/zh_CN/sound/index.rst | 7 -------
Documentation/translations/zh_CN/userspace-api/index.rst | 7 -------
Documentation/translations/zh_CN/virt/index.rst | 7 -------
Documentation/translations/zh_TW/admin-guide/index.rst | 8 --------
Documentation/translations/zh_TW/process/index.rst | 8 --------
26 files changed, 14 insertions(+), 173 deletions(-)
diff --git a/Documentation/translations/index.rst b/Documentation/translations/index.rst
index b826c34791c0..fbd7efd80507 100644
--- a/Documentation/translations/index.rst
+++ b/Documentation/translations/index.rst
@@ -57,3 +57,10 @@ in a different form.
If you need to communicate with the Linux community but you do not feel
comfortable writing in English, you can ask the translation's maintainers
for help.
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/translations/it_IT/RCU/index.rst b/Documentation/translations/it_IT/RCU/index.rst
index 22adf1d58752..e06588ccb11d 100644
--- a/Documentation/translations/it_IT/RCU/index.rst
+++ b/Documentation/translations/it_IT/RCU/index.rst
@@ -10,10 +10,3 @@ Concetti su RCU
:maxdepth: 3
torture
-
-.. only:: subproject and html
-
- Indici
- ======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/it_IT/core-api/index.rst b/Documentation/translations/it_IT/core-api/index.rst
index dad20402d11b..44320f33feb7 100644
--- a/Documentation/translations/it_IT/core-api/index.rst
+++ b/Documentation/translations/it_IT/core-api/index.rst
@@ -21,10 +21,3 @@ sul tema.
:maxdepth: 1
../RCU/index
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/it_IT/doc-guide/index.rst b/Documentation/translations/it_IT/doc-guide/index.rst
index 9fffff626711..76553a9970d0 100644
--- a/Documentation/translations/it_IT/doc-guide/index.rst
+++ b/Documentation/translations/it_IT/doc-guide/index.rst
@@ -15,10 +15,3 @@ Come scrivere la documentazione del kernel
sphinx
kernel-doc
parse-headers
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/it_IT/i2c/index.rst b/Documentation/translations/it_IT/i2c/index.rst
index 14fbe3d78299..931a8403f831 100644
--- a/Documentation/translations/it_IT/i2c/index.rst
+++ b/Documentation/translations/it_IT/i2c/index.rst
@@ -37,10 +37,3 @@ Argomenti avanzati
.. toctree::
:maxdepth: 1
-
-.. only:: subproject and html
-
- Indici
- ======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/it_IT/index.rst b/Documentation/translations/it_IT/index.rst
index afa680607750..fb10549bc729 100644
--- a/Documentation/translations/it_IT/index.rst
+++ b/Documentation/translations/it_IT/index.rst
@@ -135,3 +135,10 @@ Documentazione varia
Ci sono documenti che sono difficili da inserire nell'attuale organizzazione
della documentazione; altri hanno bisogno di essere migliorati e/o convertiti
nel formato *reStructuredText*; altri sono semplicamente troppo vecchi.
+
+.. only:: html
+
+ Indici
+ ======
+
+ * :ref:`genindex`
diff --git a/Documentation/translations/it_IT/locking/index.rst b/Documentation/translations/it_IT/locking/index.rst
index 19963d33e84d..3106466230d2 100644
--- a/Documentation/translations/it_IT/locking/index.rst
+++ b/Documentation/translations/it_IT/locking/index.rst
@@ -11,10 +11,3 @@ Sincronizzazione
lockdep-design
lockstat
locktorture
-
-.. only:: subproject and html
-
- Indici
- ======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/it_IT/process/index.rst b/Documentation/translations/it_IT/process/index.rst
index 5a5214f5fd72..d3c3354bc2c3 100644
--- a/Documentation/translations/it_IT/process/index.rst
+++ b/Documentation/translations/it_IT/process/index.rst
@@ -98,10 +98,3 @@ degli sviluppatori:
:maxdepth: 1
kernel-docs
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/admin-guide/index.rst b/Documentation/translations/zh_CN/admin-guide/index.rst
index 15d9ab5993a7..33d20c58fae9 100644
--- a/Documentation/translations/zh_CN/admin-guide/index.rst
+++ b/Documentation/translations/zh_CN/admin-guide/index.rst
@@ -123,10 +123,3 @@ Todolist:
* vga-softcursor
* video-output
* xfs
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
index 453a02cd1f44..7baccf4a4640 100644
--- a/Documentation/translations/zh_CN/core-api/index.rst
+++ b/Documentation/translations/zh_CN/core-api/index.rst
@@ -139,10 +139,3 @@ Todolist:
Todolist:
librs
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/doc-guide/index.rst b/Documentation/translations/zh_CN/doc-guide/index.rst
index 0ac1fc9315ea..faa3e4b8c518 100644
--- a/Documentation/translations/zh_CN/doc-guide/index.rst
+++ b/Documentation/translations/zh_CN/doc-guide/index.rst
@@ -19,10 +19,3 @@
contributing
maintainer-profile
checktransupdate
-
-.. only:: subproject and html
-
- 目录
- ====
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/driver-api/index.rst b/Documentation/translations/zh_CN/driver-api/index.rst
index 4050a2fb51c6..c2acb8211df5 100644
--- a/Documentation/translations/zh_CN/driver-api/index.rst
+++ b/Documentation/translations/zh_CN/driver-api/index.rst
@@ -120,10 +120,3 @@ Todolist:
* xillybus
* zorro
* hte/index
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/infiniband/index.rst b/Documentation/translations/zh_CN/infiniband/index.rst
index 5634cc48379f..5c407e727f01 100644
--- a/Documentation/translations/zh_CN/infiniband/index.rst
+++ b/Documentation/translations/zh_CN/infiniband/index.rst
@@ -29,12 +29,3 @@ infiniband
tag_matching
user_mad
user_verbs
-
-
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/kbuild/index.rst b/Documentation/translations/zh_CN/kbuild/index.rst
index 3f9ab52fa5bb..b3e2f70b5959 100644
--- a/Documentation/translations/zh_CN/kbuild/index.rst
+++ b/Documentation/translations/zh_CN/kbuild/index.rst
@@ -26,11 +26,3 @@ TODO:
- makefiles
- modules
- issues
-
-
-.. only:: subproject and html
-
- 目录
- =====
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/locking/index.rst b/Documentation/translations/zh_CN/locking/index.rst
index f0b10707668d..eab76c1a6ee7 100644
--- a/Documentation/translations/zh_CN/locking/index.rst
+++ b/Documentation/translations/zh_CN/locking/index.rst
@@ -34,10 +34,3 @@ TODOList:
* percpu-rw-semaphore
* robust-futexes
* robust-futex-ABI
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/networking/index.rst b/Documentation/translations/zh_CN/networking/index.rst
index bb0edcffd144..909ce66b2ca3 100644
--- a/Documentation/translations/zh_CN/networking/index.rst
+++ b/Documentation/translations/zh_CN/networking/index.rst
@@ -151,10 +151,3 @@ Todolist:
* xfrm_sysctl
* xdp-rx-metadata
* xsk-tx-metadata
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/peci/index.rst b/Documentation/translations/zh_CN/peci/index.rst
index 4f6694c828fa..53d3ddbf8d4e 100644
--- a/Documentation/translations/zh_CN/peci/index.rst
+++ b/Documentation/translations/zh_CN/peci/index.rst
@@ -17,10 +17,3 @@ Linux PECI 子系统
peci
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/power/index.rst b/Documentation/translations/zh_CN/power/index.rst
index bc54983ba515..65c1b76ad046 100644
--- a/Documentation/translations/zh_CN/power/index.rst
+++ b/Documentation/translations/zh_CN/power/index.rst
@@ -47,10 +47,3 @@ TODOList:
* regulator/machine
* regulator/overview
* regulator/regulator
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/process/index.rst b/Documentation/translations/zh_CN/process/index.rst
index 3bcb3bdaf533..c54a732e0e8e 100644
--- a/Documentation/translations/zh_CN/process/index.rst
+++ b/Documentation/translations/zh_CN/process/index.rst
@@ -93,10 +93,3 @@ TODOLIST:
* adding-syscalls
* botching-up-ioctls
* clang-format
-
-.. only:: subproject and html
-
- 目录
- ====
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/rust/index.rst b/Documentation/translations/zh_CN/rust/index.rst
index b01f887e7167..c8bfbed908e4 100644
--- a/Documentation/translations/zh_CN/rust/index.rst
+++ b/Documentation/translations/zh_CN/rust/index.rst
@@ -19,10 +19,3 @@ Rust
general-information
coding-guidelines
arch-support
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/scheduler/index.rst b/Documentation/translations/zh_CN/scheduler/index.rst
index a8eaa7325f54..e5fe2def2945 100644
--- a/Documentation/translations/zh_CN/scheduler/index.rst
+++ b/Documentation/translations/zh_CN/scheduler/index.rst
@@ -36,10 +36,3 @@ TODOList:
sched-rt-group
text_files
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/sound/index.rst b/Documentation/translations/zh_CN/sound/index.rst
index 28d5dca34a63..a218856c18ff 100644
--- a/Documentation/translations/zh_CN/sound/index.rst
+++ b/Documentation/translations/zh_CN/sound/index.rst
@@ -13,10 +13,3 @@ Linux 声音子系统文档
:maxdepth: 2
hd-audio/index
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/userspace-api/index.rst b/Documentation/translations/zh_CN/userspace-api/index.rst
index 5b14721c8264..dfd6590664f8 100644
--- a/Documentation/translations/zh_CN/userspace-api/index.rst
+++ b/Documentation/translations/zh_CN/userspace-api/index.rst
@@ -38,10 +38,3 @@ TODOList:
* media/index
* netlink/index
* vduse
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/virt/index.rst b/Documentation/translations/zh_CN/virt/index.rst
index f8dd13681341..59177de40d3a 100644
--- a/Documentation/translations/zh_CN/virt/index.rst
+++ b/Documentation/translations/zh_CN/virt/index.rst
@@ -29,10 +29,3 @@ TODOLIST:
kvm/index
uml/user_mode_linux_howto_v2
-
-.. only:: html and subproject
-
- Indices
- =======
-
- * :ref:`genindex`
diff --git a/Documentation/translations/zh_TW/admin-guide/index.rst b/Documentation/translations/zh_TW/admin-guide/index.rst
index 9335c0e9105d..74c98c437b91 100644
--- a/Documentation/translations/zh_TW/admin-guide/index.rst
+++ b/Documentation/translations/zh_TW/admin-guide/index.rst
@@ -126,11 +126,3 @@ Todolist:
* vga-softcursor
* video-output
* xfs
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
-
diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst
index 65922d9faa20..eb5d8794aa31 100644
--- a/Documentation/translations/zh_TW/process/index.rst
+++ b/Documentation/translations/zh_TW/process/index.rst
@@ -57,11 +57,3 @@
magic-number
volatile-considered-harmful
-
-.. only:: subproject and html
-
- 目錄
- ====
-
- * :ref:`genindex`
-
--
2.47.3
^ permalink raw reply related [flat|nested] 17+ messages in thread
* [PATCH 3/4] Documentation: include the boilerplate for SPHINXDIRS index link
2025-11-12 11:56 [PATCH 0/4] Documentation: clean up subproject index boilerplate Jani Nikula
2025-11-12 11:56 ` [PATCH 1/4] Documentation: remove subproject index links deep in the structure Jani Nikula
2025-11-12 11:56 ` [PATCH 2/4] Documentation: streamline subproject index link in translations Jani Nikula
@ 2025-11-12 11:56 ` Jani Nikula
2025-11-12 13:35 ` Mauro Carvalho Chehab
2025-11-12 11:56 ` [PATCH 4/4] Documentation: use a source-read extension to include the index boilerplate Jani Nikula
` (2 subsequent siblings)
5 siblings, 1 reply; 17+ messages in thread
From: Jani Nikula @ 2025-11-12 11:56 UTC (permalink / raw)
To: linux-doc
Cc: jani.nikula, Randy Dunlap, Mauro Carvalho Chehab, Jonathan Corbet
Repeating the index link boilerplate everywhere is tedious. Put it in a
subproject-index.rst snippet in a new sphinx-includes directory, and
include it.
We'll have to use the relative include, because a) includes are relative
to the source file, b) top level include with
/sphinx-includes/subproject-index.rst does not work with SPHINXDIRS
builds, because the root is the subdirectory in that case.
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
Documentation/RCU/index.rst | 5 +----
Documentation/accel/index.rst | 5 +----
Documentation/admin-guide/index.rst | 5 +----
Documentation/bpf/index.rst | 5 +----
Documentation/cdrom/index.rst | 5 +----
Documentation/conf.py | 2 +-
Documentation/core-api/index.rst | 5 +----
Documentation/dev-tools/index.rst | 5 +----
Documentation/doc-guide/index.rst | 5 +----
Documentation/driver-api/index.rst | 5 +----
Documentation/fault-injection/index.rst | 5 +----
Documentation/fb/index.rst | 5 +----
Documentation/fpga/index.rst | 5 +----
Documentation/gpu/drivers.rst | 5 +----
Documentation/gpu/index.rst | 5 +----
Documentation/hwmon/index.rst | 5 +----
Documentation/i2c/index.rst | 5 +----
Documentation/infiniband/index.rst | 5 +----
Documentation/input/index.rst | 5 +----
Documentation/isdn/index.rst | 5 +----
Documentation/kbuild/index.rst | 5 +----
Documentation/livepatch/index.rst | 5 +----
Documentation/locking/index.rst | 5 +----
Documentation/mhi/index.rst | 5 +----
Documentation/netlabel/index.rst | 5 +----
Documentation/networking/index.rst | 5 +----
Documentation/pcmcia/index.rst | 5 +----
Documentation/peci/index.rst | 5 +----
Documentation/power/index.rst | 5 +----
Documentation/process/index.rst | 5 +----
Documentation/rust/index.rst | 5 +----
Documentation/scheduler/index.rst | 5 +----
Documentation/sound/index.rst | 5 +----
Documentation/sphinx-includes/subproject-index.rst | 4 ++++
Documentation/spi/index.rst | 5 +----
Documentation/target/index.rst | 5 +----
Documentation/tee/index.rst | 5 +----
Documentation/timers/index.rst | 5 +----
Documentation/tools/index.rst | 5 +----
Documentation/trace/index.rst | 5 +----
Documentation/translations/index.rst | 5 +----
Documentation/usb/index.rst | 5 +----
Documentation/userspace-api/index.rst | 5 +----
Documentation/virt/index.rst | 5 +----
Documentation/w1/index.rst | 5 +----
Documentation/watchdog/index.rst | 5 +----
Documentation/wmi/index.rst | 6 +-----
47 files changed, 50 insertions(+), 182 deletions(-)
create mode 100644 Documentation/sphinx-includes/subproject-index.rst
diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
index ef26c78507d3..5a981a21f035 100644
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -31,7 +31,4 @@ RCU Handbook
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/accel/index.rst b/Documentation/accel/index.rst
index d8fa332d60a8..80039349c9c1 100644
--- a/Documentation/accel/index.rst
+++ b/Documentation/accel/index.rst
@@ -14,7 +14,4 @@ Compute Accelerators
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 259d79fbeb94..dcc9a597ea1b 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -192,7 +192,4 @@ A few hard-to-categorize and generally obsolete documents.
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst
index 0bb5cb8157f1..d7032e0b2797 100644
--- a/Documentation/bpf/index.rst
+++ b/Documentation/bpf/index.rst
@@ -36,10 +36,7 @@ that goes into great technical depth about the BPF Architecture.
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
.. Links:
.. _BPF and XDP Reference Guide: https://docs.cilium.io/en/latest/bpf/
diff --git a/Documentation/cdrom/index.rst b/Documentation/cdrom/index.rst
index 3ac4f716612f..902ee9181786 100644
--- a/Documentation/cdrom/index.rst
+++ b/Documentation/cdrom/index.rst
@@ -11,7 +11,4 @@ CD-ROM
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 574896cca198..b9a43ee32a00 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -38,7 +38,7 @@ else:
doctree = os.path.abspath(".")
# Exclude of patterns that don't contain directory names, in glob format.
-exclude_patterns = []
+exclude_patterns = ['sphinx-includes/*']
# List of patterns that contain directory names in glob format.
dyn_include_patterns = []
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index 6cbdcbfa79c3..203dc3605e04 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -142,7 +142,4 @@ Documents that don't fit elsewhere or which have yet to be categorized.
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst
index 4b8425e348ab..f74ac0caba75 100644
--- a/Documentation/dev-tools/index.rst
+++ b/Documentation/dev-tools/index.rst
@@ -42,7 +42,4 @@ Documentation/process/debugging/index.rst
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/doc-guide/index.rst b/Documentation/doc-guide/index.rst
index 24d058faa75c..3c9e509684c7 100644
--- a/Documentation/doc-guide/index.rst
+++ b/Documentation/doc-guide/index.rst
@@ -16,7 +16,4 @@ How to write kernel documentation
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 3e2a270bd828..6f2caed77490 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -150,7 +150,4 @@ Subsystem-specific APIs
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/fault-injection/index.rst b/Documentation/fault-injection/index.rst
index a6ea1d190222..91d5a8a0a8ab 100644
--- a/Documentation/fault-injection/index.rst
+++ b/Documentation/fault-injection/index.rst
@@ -14,7 +14,4 @@ Fault-injection
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/fb/index.rst b/Documentation/fb/index.rst
index e2f7488b6e2e..ce3b80494124 100644
--- a/Documentation/fb/index.rst
+++ b/Documentation/fb/index.rst
@@ -53,7 +53,4 @@ Driver documentation
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/fpga/index.rst b/Documentation/fpga/index.rst
index 43c968871d99..5977004b6ea0 100644
--- a/Documentation/fpga/index.rst
+++ b/Documentation/fpga/index.rst
@@ -11,7 +11,4 @@ FPGA
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/gpu/drivers.rst b/Documentation/gpu/drivers.rst
index 78b80be17f21..6e17e0cdcde6 100644
--- a/Documentation/gpu/drivers.rst
+++ b/Documentation/gpu/drivers.rst
@@ -29,7 +29,4 @@ GPU Driver Documentation
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: sphinx-includes/subproject-index.rst
diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst
index 7dcb15850afd..7a2ad0dc58cd 100644
--- a/Documentation/gpu/index.rst
+++ b/Documentation/gpu/index.rst
@@ -25,7 +25,4 @@ GPU Driver Developer's Guide
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst
index 51a5bdf75b08..be636db256d8 100644
--- a/Documentation/hwmon/index.rst
+++ b/Documentation/hwmon/index.rst
@@ -279,7 +279,4 @@ Hardware Monitoring Kernel Drivers
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst
index 2b213d4ce89c..41b194532b36 100644
--- a/Documentation/i2c/index.rst
+++ b/Documentation/i2c/index.rst
@@ -69,7 +69,4 @@ Legacy documentation
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/infiniband/index.rst b/Documentation/infiniband/index.rst
index 5b4c24125f66..7fa5dfec0cdd 100644
--- a/Documentation/infiniband/index.rst
+++ b/Documentation/infiniband/index.rst
@@ -18,7 +18,4 @@ InfiniBand
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/input/index.rst b/Documentation/input/index.rst
index 35581cd18e91..bbf458cc539f 100644
--- a/Documentation/input/index.rst
+++ b/Documentation/input/index.rst
@@ -13,7 +13,4 @@ Contents:
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/isdn/index.rst b/Documentation/isdn/index.rst
index 9622939fa526..4b95621f0caf 100644
--- a/Documentation/isdn/index.rst
+++ b/Documentation/isdn/index.rst
@@ -15,7 +15,4 @@ ISDN
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/kbuild/index.rst b/Documentation/kbuild/index.rst
index 3731ab22bfe7..89a458f422a3 100644
--- a/Documentation/kbuild/index.rst
+++ b/Documentation/kbuild/index.rst
@@ -27,7 +27,4 @@ Kernel Build System
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/livepatch/index.rst b/Documentation/livepatch/index.rst
index cebf1c71d4a5..1e1db6f3f89f 100644
--- a/Documentation/livepatch/index.rst
+++ b/Documentation/livepatch/index.rst
@@ -18,7 +18,4 @@ Kernel Livepatching
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/locking/index.rst b/Documentation/locking/index.rst
index 6a9ea96c8bcb..ef6b2d5cdb70 100644
--- a/Documentation/locking/index.rst
+++ b/Documentation/locking/index.rst
@@ -27,7 +27,4 @@ Locking
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/mhi/index.rst b/Documentation/mhi/index.rst
index 1d8dec302780..2cbfe3546a56 100644
--- a/Documentation/mhi/index.rst
+++ b/Documentation/mhi/index.rst
@@ -12,7 +12,4 @@ MHI
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/netlabel/index.rst b/Documentation/netlabel/index.rst
index 984e1b191b12..950da3009cad 100644
--- a/Documentation/netlabel/index.rst
+++ b/Documentation/netlabel/index.rst
@@ -15,7 +15,4 @@ NetLabel
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index c775cababc8c..5e59b14d9e4e 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -140,7 +140,4 @@ Contents:
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/pcmcia/index.rst b/Documentation/pcmcia/index.rst
index 8067236c51ab..36373e6b9eb1 100644
--- a/Documentation/pcmcia/index.rst
+++ b/Documentation/pcmcia/index.rst
@@ -14,7 +14,4 @@ PCMCIA
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/peci/index.rst b/Documentation/peci/index.rst
index 930e75217c33..eb9aff64abbd 100644
--- a/Documentation/peci/index.rst
+++ b/Documentation/peci/index.rst
@@ -10,7 +10,4 @@ PECI Subsystem
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/power/index.rst b/Documentation/power/index.rst
index a0f5244fb427..cabf2841e8d9 100644
--- a/Documentation/power/index.rst
+++ b/Documentation/power/index.rst
@@ -40,7 +40,4 @@ Power Management
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index aa12f2660194..cfc86f67630c 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -111,7 +111,4 @@ developers:
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst
index ec62001c7d8c..7400f5076764 100644
--- a/Documentation/rust/index.rst
+++ b/Documentation/rust/index.rst
@@ -61,7 +61,4 @@ You can also find learning materials for Rust in its section in
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/scheduler/index.rst b/Documentation/scheduler/index.rst
index 5dd53e47bc0c..88f957a9b515 100644
--- a/Documentation/scheduler/index.rst
+++ b/Documentation/scheduler/index.rst
@@ -28,7 +28,4 @@ Scheduler
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst
index 51cd736f65b5..1bc480b65369 100644
--- a/Documentation/sound/index.rst
+++ b/Documentation/sound/index.rst
@@ -18,7 +18,4 @@ Sound Subsystem Documentation
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/sphinx-includes/subproject-index.rst b/Documentation/sphinx-includes/subproject-index.rst
new file mode 100644
index 000000000000..4113bf1c3085
--- /dev/null
+++ b/Documentation/sphinx-includes/subproject-index.rst
@@ -0,0 +1,4 @@
+Indices
+=======
+
+* :ref:`genindex`
diff --git a/Documentation/spi/index.rst b/Documentation/spi/index.rst
index 824ce42ed4f0..3fd67d4ec3fa 100644
--- a/Documentation/spi/index.rst
+++ b/Documentation/spi/index.rst
@@ -15,7 +15,4 @@ Serial Peripheral Interface (SPI)
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/target/index.rst b/Documentation/target/index.rst
index 4b24f81f747e..518a2dae2073 100644
--- a/Documentation/target/index.rst
+++ b/Documentation/target/index.rst
@@ -13,7 +13,4 @@ TCM Virtual Device
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/tee/index.rst b/Documentation/tee/index.rst
index 62afb7ee9b52..fd438e69a035 100644
--- a/Documentation/tee/index.rst
+++ b/Documentation/tee/index.rst
@@ -15,7 +15,4 @@ TEE Subsystem
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/timers/index.rst b/Documentation/timers/index.rst
index 4e88116e4dcf..5db11fbcb4b3 100644
--- a/Documentation/timers/index.rst
+++ b/Documentation/timers/index.rst
@@ -16,7 +16,4 @@ Timers
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/tools/index.rst b/Documentation/tools/index.rst
index 80488e290e10..b6059307f413 100644
--- a/Documentation/tools/index.rst
+++ b/Documentation/tools/index.rst
@@ -15,7 +15,4 @@ more additions are needed here:
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
index b4a429dc4f7a..38bb76ad751a 100644
--- a/Documentation/trace/index.rst
+++ b/Documentation/trace/index.rst
@@ -98,7 +98,4 @@ tracing tool and framework.
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/translations/index.rst b/Documentation/translations/index.rst
index fbd7efd80507..8dd6ea1fd670 100644
--- a/Documentation/translations/index.rst
+++ b/Documentation/translations/index.rst
@@ -60,7 +60,4 @@ for help.
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/usb/index.rst b/Documentation/usb/index.rst
index 826492c813ac..1014b07df9fb 100644
--- a/Documentation/usb/index.rst
+++ b/Documentation/usb/index.rst
@@ -34,7 +34,4 @@ USB support
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst
index b8c73be4fb11..7936933fd93b 100644
--- a/Documentation/userspace-api/index.rst
+++ b/Documentation/userspace-api/index.rst
@@ -70,7 +70,4 @@ Everything else
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/virt/index.rst b/Documentation/virt/index.rst
index 7fb55ae08598..0e1371664d2e 100644
--- a/Documentation/virt/index.rst
+++ b/Documentation/virt/index.rst
@@ -19,7 +19,4 @@ Virtualization Support
.. only:: html and subproject
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/w1/index.rst b/Documentation/w1/index.rst
index 156279f17553..8fc0299aa2cd 100644
--- a/Documentation/w1/index.rst
+++ b/Documentation/w1/index.rst
@@ -15,7 +15,4 @@
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/watchdog/index.rst b/Documentation/watchdog/index.rst
index 4603f2511f58..16e72a9bf4de 100644
--- a/Documentation/watchdog/index.rst
+++ b/Documentation/watchdog/index.rst
@@ -19,7 +19,4 @@ Watchdog Support
.. only:: subproject and html
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/wmi/index.rst b/Documentation/wmi/index.rst
index fec4b6ae97b3..5f0856f8831c 100644
--- a/Documentation/wmi/index.rst
+++ b/Documentation/wmi/index.rst
@@ -13,8 +13,4 @@ WMI Subsystem
.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
+ .. include:: ../sphinx-includes/subproject-index.rst
--
2.47.3
^ permalink raw reply related [flat|nested] 17+ messages in thread
* [PATCH 4/4] Documentation: use a source-read extension to include the index boilerplate
2025-11-12 11:56 [PATCH 0/4] Documentation: clean up subproject index boilerplate Jani Nikula
` (2 preceding siblings ...)
2025-11-12 11:56 ` [PATCH 3/4] Documentation: include the boilerplate for SPHINXDIRS index link Jani Nikula
@ 2025-11-12 11:56 ` Jani Nikula
2025-11-12 13:39 ` Mauro Carvalho Chehab
2025-11-13 6:50 ` [PATCH 0/4] Documentation: clean up subproject " Randy Dunlap
2025-11-13 16:33 ` Jonathan Corbet
5 siblings, 1 reply; 17+ messages in thread
From: Jani Nikula @ 2025-11-12 11:56 UTC (permalink / raw)
To: linux-doc
Cc: jani.nikula, Randy Dunlap, Mauro Carvalho Chehab, Jonathan Corbet
Reduce boilerplate all over the place by adding a small ad hoc extension
in conf.py that adds the ../sphinx-includes/subproject-index.rst include
to all SPHINXDIRS builds.
Note that the docname is just 'index', because the SPHINXDIRS builds
happen in the subdirectories.
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
Documentation/RCU/index.rst | 4 ----
Documentation/accel/index.rst | 4 ----
Documentation/admin-guide/index.rst | 4 ----
Documentation/bpf/index.rst | 4 ----
Documentation/cdrom/index.rst | 4 ----
Documentation/conf.py | 6 ++++++
Documentation/core-api/index.rst | 4 ----
Documentation/dev-tools/index.rst | 5 -----
Documentation/doc-guide/index.rst | 4 ----
Documentation/driver-api/index.rst | 4 ----
Documentation/fault-injection/index.rst | 4 ----
Documentation/fb/index.rst | 4 ----
Documentation/fpga/index.rst | 4 ----
Documentation/gpu/drivers.rst | 4 ----
Documentation/gpu/index.rst | 4 ----
Documentation/hwmon/index.rst | 4 ----
Documentation/i2c/index.rst | 4 ----
Documentation/infiniband/index.rst | 4 ----
Documentation/input/index.rst | 4 ----
Documentation/isdn/index.rst | 4 ----
Documentation/kbuild/index.rst | 4 ----
Documentation/livepatch/index.rst | 4 ----
Documentation/locking/index.rst | 4 ----
Documentation/mhi/index.rst | 4 ----
Documentation/netlabel/index.rst | 4 ----
Documentation/networking/index.rst | 4 ----
Documentation/pcmcia/index.rst | 4 ----
Documentation/peci/index.rst | 4 ----
Documentation/power/index.rst | 4 ----
Documentation/process/index.rst | 4 ----
Documentation/rust/index.rst | 4 ----
Documentation/scheduler/index.rst | 4 ----
Documentation/sound/index.rst | 4 ----
Documentation/spi/index.rst | 4 ----
Documentation/target/index.rst | 4 ----
Documentation/tee/index.rst | 4 ----
Documentation/timers/index.rst | 4 ----
Documentation/tools/index.rst | 4 ----
Documentation/trace/index.rst | 4 ----
Documentation/translations/index.rst | 4 ----
Documentation/usb/index.rst | 4 ----
Documentation/userspace-api/index.rst | 4 ----
Documentation/virt/index.rst | 4 ----
Documentation/w1/index.rst | 4 ----
Documentation/watchdog/index.rst | 4 ----
Documentation/wmi/index.rst | 4 ----
46 files changed, 6 insertions(+), 181 deletions(-)
diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
index 5a981a21f035..035871687ee2 100644
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -28,7 +28,3 @@ RCU Handbook
Design/Expedited-Grace-Periods/Expedited-Grace-Periods
Design/Requirements/Requirements
Design/Data-Structures/Data-Structures
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/accel/index.rst b/Documentation/accel/index.rst
index 80039349c9c1..cbc7d4c3876a 100644
--- a/Documentation/accel/index.rst
+++ b/Documentation/accel/index.rst
@@ -11,7 +11,3 @@ Compute Accelerators
amdxdna/index
qaic/index
rocket/index
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index dcc9a597ea1b..b734f8a2a2c4 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -189,7 +189,3 @@ A few hard-to-categorize and generally obsolete documents.
ldm
unicode
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst
index d7032e0b2797..0d5c6f659266 100644
--- a/Documentation/bpf/index.rst
+++ b/Documentation/bpf/index.rst
@@ -34,9 +34,5 @@ that goes into great technical depth about the BPF Architecture.
other
redirect
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
-
.. Links:
.. _BPF and XDP Reference Guide: https://docs.cilium.io/en/latest/bpf/
diff --git a/Documentation/cdrom/index.rst b/Documentation/cdrom/index.rst
index 902ee9181786..50050e219910 100644
--- a/Documentation/cdrom/index.rst
+++ b/Documentation/cdrom/index.rst
@@ -8,7 +8,3 @@ CD-ROM
:maxdepth: 1
cdrom-standard
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/conf.py b/Documentation/conf.py
index b9a43ee32a00..cb0936a71d52 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -589,8 +589,14 @@ kerneldoc_srctree = ".."
# ------------------------------------------------------------------------------
loadConfig(globals())
+# Add index link to SPHINXDIRS builds
+def add_subproject_index(app, docname, source):
+ if app.builder.tags.has('subproject') and app.builder.tags.has('html'):
+ if docname == 'index':
+ source[0] += '\n.. include:: ../sphinx-includes/subproject-index.rst\n'
def setup(app):
"""Patterns need to be updated at init time on older Sphinx versions"""
app.connect('config-inited', config_init)
+ app.connect("source-read", add_subproject_index)
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index 203dc3605e04..cb04a579a4b7 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -139,7 +139,3 @@ Documents that don't fit elsewhere or which have yet to be categorized.
librs
netlink
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst
index f74ac0caba75..4fc9d15f91d0 100644
--- a/Documentation/dev-tools/index.rst
+++ b/Documentation/dev-tools/index.rst
@@ -38,8 +38,3 @@ Documentation/process/debugging/index.rst
gpio-sloppy-logic-analyzer
autofdo
propeller
-
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/doc-guide/index.rst b/Documentation/doc-guide/index.rst
index 3c9e509684c7..f078baddf0b7 100644
--- a/Documentation/doc-guide/index.rst
+++ b/Documentation/doc-guide/index.rst
@@ -13,7 +13,3 @@ How to write kernel documentation
contributing
maintainer-profile
checktransupdate
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 6f2caed77490..8c720a913060 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -147,7 +147,3 @@ Subsystem-specific APIs
wmi
xilinx/index
zorro
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/fault-injection/index.rst b/Documentation/fault-injection/index.rst
index 91d5a8a0a8ab..2a9e30b4202c 100644
--- a/Documentation/fault-injection/index.rst
+++ b/Documentation/fault-injection/index.rst
@@ -11,7 +11,3 @@ Fault-injection
notifier-error-inject
nvme-fault-injection
provoke-crashes
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/fb/index.rst b/Documentation/fb/index.rst
index ce3b80494124..fe9ca3570941 100644
--- a/Documentation/fb/index.rst
+++ b/Documentation/fb/index.rst
@@ -50,7 +50,3 @@ Driver documentation
vesafb
viafb
vt8623fb
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/fpga/index.rst b/Documentation/fpga/index.rst
index 5977004b6ea0..c5a876165dab 100644
--- a/Documentation/fpga/index.rst
+++ b/Documentation/fpga/index.rst
@@ -8,7 +8,3 @@ FPGA
:maxdepth: 1
dfl
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/gpu/drivers.rst b/Documentation/gpu/drivers.rst
index 6e17e0cdcde6..2e13e0ad7e88 100644
--- a/Documentation/gpu/drivers.rst
+++ b/Documentation/gpu/drivers.rst
@@ -26,7 +26,3 @@ GPU Driver Documentation
panthor
zynqmp
nova/index
-
-.. only:: subproject and html
-
- .. include:: sphinx-includes/subproject-index.rst
diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst
index 7a2ad0dc58cd..2fafa1f35ef3 100644
--- a/Documentation/gpu/index.rst
+++ b/Documentation/gpu/index.rst
@@ -22,7 +22,3 @@ GPU Driver Developer's Guide
implementation_guidelines
todo
rfc/index
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst
index be636db256d8..c4510e773549 100644
--- a/Documentation/hwmon/index.rst
+++ b/Documentation/hwmon/index.rst
@@ -276,7 +276,3 @@ Hardware Monitoring Kernel Drivers
xdpe12284
xdpe152c4
zl6100
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst
index 41b194532b36..ccf13718ce70 100644
--- a/Documentation/i2c/index.rst
+++ b/Documentation/i2c/index.rst
@@ -66,7 +66,3 @@ Legacy documentation
:maxdepth: 1
old-module-parameters
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/infiniband/index.rst b/Documentation/infiniband/index.rst
index 7fa5dfec0cdd..c11049d25703 100644
--- a/Documentation/infiniband/index.rst
+++ b/Documentation/infiniband/index.rst
@@ -15,7 +15,3 @@ InfiniBand
ucaps
user_mad
user_verbs
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/input/index.rst b/Documentation/input/index.rst
index bbf458cc539f..fbde5bc9f641 100644
--- a/Documentation/input/index.rst
+++ b/Documentation/input/index.rst
@@ -10,7 +10,3 @@ Contents:
input_uapi
input_kapi
devices/index
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/isdn/index.rst b/Documentation/isdn/index.rst
index 4b95621f0caf..d1125a16a746 100644
--- a/Documentation/isdn/index.rst
+++ b/Documentation/isdn/index.rst
@@ -12,7 +12,3 @@ ISDN
m_isdn
credits
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/kbuild/index.rst b/Documentation/kbuild/index.rst
index 89a458f422a3..f46233be82b9 100644
--- a/Documentation/kbuild/index.rst
+++ b/Documentation/kbuild/index.rst
@@ -24,7 +24,3 @@ Kernel Build System
gendwarfksyms
bash-completion
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/livepatch/index.rst b/Documentation/livepatch/index.rst
index 1e1db6f3f89f..d2e7aa0f7f89 100644
--- a/Documentation/livepatch/index.rst
+++ b/Documentation/livepatch/index.rst
@@ -15,7 +15,3 @@ Kernel Livepatching
system-state
reliable-stacktrace
api
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/locking/index.rst b/Documentation/locking/index.rst
index ef6b2d5cdb70..9278d95b7dcb 100644
--- a/Documentation/locking/index.rst
+++ b/Documentation/locking/index.rst
@@ -24,7 +24,3 @@ Locking
percpu-rw-semaphore
robust-futexes
robust-futex-ABI
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/mhi/index.rst b/Documentation/mhi/index.rst
index 2cbfe3546a56..0aa00482aa2e 100644
--- a/Documentation/mhi/index.rst
+++ b/Documentation/mhi/index.rst
@@ -9,7 +9,3 @@ MHI
mhi
topology
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/netlabel/index.rst b/Documentation/netlabel/index.rst
index 950da3009cad..bb6ba7d5c200 100644
--- a/Documentation/netlabel/index.rst
+++ b/Documentation/netlabel/index.rst
@@ -12,7 +12,3 @@ NetLabel
lsm_interface
draft_ietf
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index 5e59b14d9e4e..c322fd1bbe26 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -137,7 +137,3 @@ Contents:
xfrm_sysctl
xdp-rx-metadata
xsk-tx-metadata
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/pcmcia/index.rst b/Documentation/pcmcia/index.rst
index 36373e6b9eb1..89c004816140 100644
--- a/Documentation/pcmcia/index.rst
+++ b/Documentation/pcmcia/index.rst
@@ -11,7 +11,3 @@ PCMCIA
devicetable
locking
driver-changes
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/peci/index.rst b/Documentation/peci/index.rst
index eb9aff64abbd..1443c31a0d18 100644
--- a/Documentation/peci/index.rst
+++ b/Documentation/peci/index.rst
@@ -7,7 +7,3 @@ PECI Subsystem
.. toctree::
peci
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/power/index.rst b/Documentation/power/index.rst
index cabf2841e8d9..ffc38b7c7380 100644
--- a/Documentation/power/index.rst
+++ b/Documentation/power/index.rst
@@ -37,7 +37,3 @@ Power Management
regulator/machine
regulator/overview
regulator/regulator
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index cfc86f67630c..02936d667b40 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -108,7 +108,3 @@ developers:
kernel-docs
deprecated
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst
index 7400f5076764..7a31843cd4a3 100644
--- a/Documentation/rust/index.rst
+++ b/Documentation/rust/index.rst
@@ -58,7 +58,3 @@ more details.
You can also find learning materials for Rust in its section in
:doc:`../process/kernel-docs`.
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/scheduler/index.rst b/Documentation/scheduler/index.rst
index 88f957a9b515..17ce8d76befc 100644
--- a/Documentation/scheduler/index.rst
+++ b/Documentation/scheduler/index.rst
@@ -25,7 +25,3 @@ Scheduler
sched-debug
text_files
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst
index 1bc480b65369..c075ca6e11eb 100644
--- a/Documentation/sound/index.rst
+++ b/Documentation/sound/index.rst
@@ -15,7 +15,3 @@ Sound Subsystem Documentation
cards/index
codecs/index
utimers
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/spi/index.rst b/Documentation/spi/index.rst
index 3fd67d4ec3fa..20d4a4185ab9 100644
--- a/Documentation/spi/index.rst
+++ b/Documentation/spi/index.rst
@@ -12,7 +12,3 @@ Serial Peripheral Interface (SPI)
butterfly
spi-lm70llp
spi-sc18is602
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/target/index.rst b/Documentation/target/index.rst
index 518a2dae2073..51fa8ebc652e 100644
--- a/Documentation/target/index.rst
+++ b/Documentation/target/index.rst
@@ -10,7 +10,3 @@ TCM Virtual Device
tcmu-design
tcm_mod_builder
scripts
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/tee/index.rst b/Documentation/tee/index.rst
index fd438e69a035..10c3cecde85d 100644
--- a/Documentation/tee/index.rst
+++ b/Documentation/tee/index.rst
@@ -12,7 +12,3 @@ TEE Subsystem
amd-tee
ts-tee
qtee
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/timers/index.rst b/Documentation/timers/index.rst
index 5db11fbcb4b3..c8352756b480 100644
--- a/Documentation/timers/index.rst
+++ b/Documentation/timers/index.rst
@@ -13,7 +13,3 @@ Timers
no_hz
timekeeping
delay_sleep_functions
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/tools/index.rst b/Documentation/tools/index.rst
index b6059307f413..27488bd3eb91 100644
--- a/Documentation/tools/index.rst
+++ b/Documentation/tools/index.rst
@@ -12,7 +12,3 @@ more additions are needed here:
rtla/index
rv/index
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
index 38bb76ad751a..cfd8128ac56d 100644
--- a/Documentation/trace/index.rst
+++ b/Documentation/trace/index.rst
@@ -95,7 +95,3 @@ Additional Resources
For more details, refer to the respective documentation of each
tracing tool and framework.
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/translations/index.rst b/Documentation/translations/index.rst
index 8dd6ea1fd670..b826c34791c0 100644
--- a/Documentation/translations/index.rst
+++ b/Documentation/translations/index.rst
@@ -57,7 +57,3 @@ in a different form.
If you need to communicate with the Linux community but you do not feel
comfortable writing in English, you can ask the translation's maintainers
for help.
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/usb/index.rst b/Documentation/usb/index.rst
index 1014b07df9fb..605233febd7a 100644
--- a/Documentation/usb/index.rst
+++ b/Documentation/usb/index.rst
@@ -31,7 +31,3 @@ USB support
usb-help
text_files
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst
index 7936933fd93b..76805a1052e2 100644
--- a/Documentation/userspace-api/index.rst
+++ b/Documentation/userspace-api/index.rst
@@ -67,7 +67,3 @@ Everything else
futex2
perf_ring_buffer
ntsync
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/virt/index.rst b/Documentation/virt/index.rst
index 0e1371664d2e..c1f0bbc37315 100644
--- a/Documentation/virt/index.rst
+++ b/Documentation/virt/index.rst
@@ -16,7 +16,3 @@ Virtualization Support
coco/sev-guest
coco/tdx-guest
hyperv/index
-
-.. only:: html and subproject
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/w1/index.rst b/Documentation/w1/index.rst
index 8fc0299aa2cd..2e7bd8afea84 100644
--- a/Documentation/w1/index.rst
+++ b/Documentation/w1/index.rst
@@ -12,7 +12,3 @@
w1-netlink.rst
masters/index
slaves/index
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/watchdog/index.rst b/Documentation/watchdog/index.rst
index 16e72a9bf4de..1cea24681e6b 100644
--- a/Documentation/watchdog/index.rst
+++ b/Documentation/watchdog/index.rst
@@ -16,7 +16,3 @@ Watchdog Support
watchdog-pm
wdt
convert_drivers_to_kernel_api
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
diff --git a/Documentation/wmi/index.rst b/Documentation/wmi/index.rst
index 5f0856f8831c..56016078fc79 100644
--- a/Documentation/wmi/index.rst
+++ b/Documentation/wmi/index.rst
@@ -10,7 +10,3 @@ WMI Subsystem
acpi-interface
driver-development-guide
devices/index
-
-.. only:: subproject and html
-
- .. include:: ../sphinx-includes/subproject-index.rst
--
2.47.3
^ permalink raw reply related [flat|nested] 17+ messages in thread
* Re: [PATCH 1/4] Documentation: remove subproject index links deep in the structure
2025-11-12 11:56 ` [PATCH 1/4] Documentation: remove subproject index links deep in the structure Jani Nikula
@ 2025-11-12 13:27 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 17+ messages in thread
From: Mauro Carvalho Chehab @ 2025-11-12 13:27 UTC (permalink / raw)
To: Jani Nikula
Cc: linux-doc, Randy Dunlap, Mauro Carvalho Chehab, Jonathan Corbet
On Wed, Nov 12, 2025 at 01:56:51PM +0200, Jani Nikula wrote:
> The idea of having
>
> .. only:: subproject and html
>
> Indices
> =======
>
> * :ref:`genindex`
>
> in index.rst pages is to add the index link to the main page of the
> subproject when doing SPHINXDIRS builds. There's no such need deeper in
> the documentation structure, and we can safely get rid of them. In all
> likelihood, it's just cargo culted and copy-pasted.
>
> Cc: Randy Dunlap <rdunlap@infradead.org>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Patch series look OK on my eyes and works as expected, but there is
an issue on patch 4 (I'll comment about it there).
Also, they didn't apply on the top of docs/docs-next (or docs-mw),
so I suspect you need to rebase it.
Regards,
Mauro
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 3/4] Documentation: include the boilerplate for SPHINXDIRS index link
2025-11-12 11:56 ` [PATCH 3/4] Documentation: include the boilerplate for SPHINXDIRS index link Jani Nikula
@ 2025-11-12 13:35 ` Mauro Carvalho Chehab
2025-11-13 8:04 ` Jani Nikula
0 siblings, 1 reply; 17+ messages in thread
From: Mauro Carvalho Chehab @ 2025-11-12 13:35 UTC (permalink / raw)
To: Jani Nikula
Cc: linux-doc, Randy Dunlap, Mauro Carvalho Chehab, Jonathan Corbet
On Wed, Nov 12, 2025 at 01:56:53PM +0200, Jani Nikula wrote:
> Repeating the index link boilerplate everywhere is tedious. Put it in a
> subproject-index.rst snippet in a new sphinx-includes directory, and
> include it.
>
> We'll have to use the relative include, because a) includes are relative
> to the source file, b) top level include with
> /sphinx-includes/subproject-index.rst does not work with SPHINXDIRS
> builds, because the root is the subdirectory in that case.
>
> Cc: Randy Dunlap <rdunlap@infradead.org>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 574896cca198..b9a43ee32a00 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -38,7 +38,7 @@ else:
> doctree = os.path.abspath(".")
>
> # Exclude of patterns that don't contain directory names, in glob format.
> -exclude_patterns = []
> +exclude_patterns = ['sphinx-includes/*']
This doesn't work the way on might expect. The problem also affects
patch 4.
Basically, when SUBDIRS is used, include and exclude patterns need
to be dynamically calculated, as, instead of building docs using
Documentation/, the logic builds inside documentation/<directory>
So, instead, you need to do:
dyn_exclude_patterns.append("sphinx-includes/*")
To ensure that it will pick just the right includes directory.
Regards,
Mauro
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 4/4] Documentation: use a source-read extension to include the index boilerplate
2025-11-12 11:56 ` [PATCH 4/4] Documentation: use a source-read extension to include the index boilerplate Jani Nikula
@ 2025-11-12 13:39 ` Mauro Carvalho Chehab
2025-11-13 8:12 ` Jani Nikula
0 siblings, 1 reply; 17+ messages in thread
From: Mauro Carvalho Chehab @ 2025-11-12 13:39 UTC (permalink / raw)
To: Jani Nikula
Cc: linux-doc, Randy Dunlap, Mauro Carvalho Chehab, Jonathan Corbet
On Wed, Nov 12, 2025 at 01:56:54PM +0200, Jani Nikula wrote:
> Reduce boilerplate all over the place by adding a small ad hoc extension
> in conf.py that adds the ../sphinx-includes/subproject-index.rst include
> to all SPHINXDIRS builds.
>
> Note that the docname is just 'index', because the SPHINXDIRS builds
> happen in the subdirectories.
>
> Cc: Randy Dunlap <rdunlap@infradead.org>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index b9a43ee32a00..cb0936a71d52 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -589,8 +589,14 @@ kerneldoc_srctree = ".."
> # ------------------------------------------------------------------------------
> loadConfig(globals())
>
> +# Add index link to SPHINXDIRS builds
> +def add_subproject_index(app, docname, source):
> + if app.builder.tags.has('subproject') and app.builder.tags.has('html'):
> + if docname == 'index':
> + source[0] += '\n.. include:: ../sphinx-includes/subproject-index.rst\n'
The relative path there breaks SPINXDIRS, when it is pointing to use a sub-sub-dir
like:
$ make SPHINXDIRS=userspace-api/media htmldocs
Traceback
=========
File "/usr/lib/python3.14/site-packages/sphinx/util/parallel.py", line 137, in _join_one
raise SphinxParallelError(*result)
sphinx.errors.SphinxParallelError: docutils.utils.SystemMessage: Documentation/userspace-api/media/index.rst:69: (SEVERE/4) Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'Documentation/userspace-api/sphinx-includes/subproject-index.rst'.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 0/4] Documentation: clean up subproject index boilerplate
2025-11-12 11:56 [PATCH 0/4] Documentation: clean up subproject index boilerplate Jani Nikula
` (3 preceding siblings ...)
2025-11-12 11:56 ` [PATCH 4/4] Documentation: use a source-read extension to include the index boilerplate Jani Nikula
@ 2025-11-13 6:50 ` Randy Dunlap
2025-11-13 16:33 ` Jonathan Corbet
5 siblings, 0 replies; 17+ messages in thread
From: Randy Dunlap @ 2025-11-13 6:50 UTC (permalink / raw)
To: Jani Nikula, linux-doc
On 11/12/25 3:56 AM, Jani Nikula wrote:
> Only very lightly tested.
>
> Jani Nikula (4):
> Documentation: remove subproject index links deep in the structure
> Documentation: streamline subproject index link in translations
> Documentation: include the boilerplate for SPHINXDIRS index link
> Documentation: use a source-read extension to include the index
> boilerplate
>
> 136 files changed, 18 insertions(+), 935 deletions(-)
> create mode 100644 Documentation/sphinx-includes/subproject-index.rst
>
Applies to kernel version 6.18-rc5 or maybe some patches on top of that.
Thanks for the quick reply. I applaud the changes but I'm going to wait
to test them until an update to address Mauro's comments.
--
~Randy
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 3/4] Documentation: include the boilerplate for SPHINXDIRS index link
2025-11-12 13:35 ` Mauro Carvalho Chehab
@ 2025-11-13 8:04 ` Jani Nikula
2025-11-13 10:11 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 17+ messages in thread
From: Jani Nikula @ 2025-11-13 8:04 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: linux-doc, Randy Dunlap, Mauro Carvalho Chehab, Jonathan Corbet
On Wed, 12 Nov 2025, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> On Wed, Nov 12, 2025 at 01:56:53PM +0200, Jani Nikula wrote:
>> Repeating the index link boilerplate everywhere is tedious. Put it in a
>> subproject-index.rst snippet in a new sphinx-includes directory, and
>> include it.
>>
>> We'll have to use the relative include, because a) includes are relative
>> to the source file, b) top level include with
>> /sphinx-includes/subproject-index.rst does not work with SPHINXDIRS
>> builds, because the root is the subdirectory in that case.
>>
>> Cc: Randy Dunlap <rdunlap@infradead.org>
>> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>> Cc: Jonathan Corbet <corbet@lwn.net>
>> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
>
>
>> diff --git a/Documentation/conf.py b/Documentation/conf.py
>> index 574896cca198..b9a43ee32a00 100644
>> --- a/Documentation/conf.py
>> +++ b/Documentation/conf.py
>> @@ -38,7 +38,7 @@ else:
>> doctree = os.path.abspath(".")
>>
>> # Exclude of patterns that don't contain directory names, in glob format.
>> -exclude_patterns = []
>> +exclude_patterns = ['sphinx-includes/*']
>
> This doesn't work the way on might expect. The problem also affects
> patch 4.
>
> Basically, when SUBDIRS is used, include and exclude patterns need
> to be dynamically calculated, as, instead of building docs using
>
> Documentation/, the logic builds inside documentation/<directory>
>
> So, instead, you need to do:
>
> dyn_exclude_patterns.append("sphinx-includes/*")
>
> To ensure that it will pick just the right includes directory.
Sphinx will only look for files within the source directory passed to
sphinx-build. With SPHINXDIRS, the Documentation/ is not it. There's no
need to specifically exclude anything that's outside of the source
directory hierarchy.
The whole dyn_exclude_patterns looks like overkill to me. It should just
look at exclude_patterns, and remove anything that's outside of the
SPHINXDIRS specified, and remove the SPHINXDIRS prefix from the
remaining ones.
In any case, the above exclude_patterns setting will work just fine.
BR,
Jani.
--
Jani Nikula, Intel
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 4/4] Documentation: use a source-read extension to include the index boilerplate
2025-11-12 13:39 ` Mauro Carvalho Chehab
@ 2025-11-13 8:12 ` Jani Nikula
2025-11-13 10:25 ` Mauro Carvalho Chehab
2025-11-13 19:36 ` Randy Dunlap
0 siblings, 2 replies; 17+ messages in thread
From: Jani Nikula @ 2025-11-13 8:12 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: linux-doc, Randy Dunlap, Mauro Carvalho Chehab, Jonathan Corbet
On Wed, 12 Nov 2025, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> On Wed, Nov 12, 2025 at 01:56:54PM +0200, Jani Nikula wrote:
>> Reduce boilerplate all over the place by adding a small ad hoc extension
>> in conf.py that adds the ../sphinx-includes/subproject-index.rst include
>> to all SPHINXDIRS builds.
>>
>> Note that the docname is just 'index', because the SPHINXDIRS builds
>> happen in the subdirectories.
>>
>> Cc: Randy Dunlap <rdunlap@infradead.org>
>> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>> Cc: Jonathan Corbet <corbet@lwn.net>
>> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
>
>> diff --git a/Documentation/conf.py b/Documentation/conf.py
>> index b9a43ee32a00..cb0936a71d52 100644
>> --- a/Documentation/conf.py
>> +++ b/Documentation/conf.py
>> @@ -589,8 +589,14 @@ kerneldoc_srctree = ".."
>> # ------------------------------------------------------------------------------
>> loadConfig(globals())
>>
>> +# Add index link to SPHINXDIRS builds
>> +def add_subproject_index(app, docname, source):
>> + if app.builder.tags.has('subproject') and app.builder.tags.has('html'):
>> + if docname == 'index':
>> + source[0] += '\n.. include:: ../sphinx-includes/subproject-index.rst\n'
>
> The relative path there breaks SPINXDIRS, when it is pointing to use a sub-sub-dir
> like:
>
> $ make SPHINXDIRS=userspace-api/media htmldocs
Ugh, I looked at 'make help' for the "valid values for SPHINXDIRS",
which only lists the top level directories. Patch 1 is also based on
this.
What a surprise, the documentation for documentation is useless.
BR,
Jani.
>
> Traceback =========
>
> File "/usr/lib/python3.14/site-packages/sphinx/util/parallel.py", line 137, in _join_one
> raise SphinxParallelError(*result)
> sphinx.errors.SphinxParallelError: docutils.utils.SystemMessage: Documentation/userspace-api/media/index.rst:69: (SEVERE/4) Problems with "include" directive path:
> InputError: [Errno 2] No such file or directory: 'Documentation/userspace-api/sphinx-includes/subproject-index.rst'.
>
> Thanks,
> Mauro
--
Jani Nikula, Intel
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 3/4] Documentation: include the boilerplate for SPHINXDIRS index link
2025-11-13 8:04 ` Jani Nikula
@ 2025-11-13 10:11 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 17+ messages in thread
From: Mauro Carvalho Chehab @ 2025-11-13 10:11 UTC (permalink / raw)
To: Jani Nikula
Cc: Mauro Carvalho Chehab, linux-doc, Randy Dunlap, Jonathan Corbet
On Thu, Nov 13, 2025 at 10:04:17AM +0200, Jani Nikula wrote:
> On Wed, 12 Nov 2025, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> > On Wed, Nov 12, 2025 at 01:56:53PM +0200, Jani Nikula wrote:
> >> Repeating the index link boilerplate everywhere is tedious. Put it in a
> >> subproject-index.rst snippet in a new sphinx-includes directory, and
> >> include it.
> >>
> >> We'll have to use the relative include, because a) includes are relative
> >> to the source file, b) top level include with
> >> /sphinx-includes/subproject-index.rst does not work with SPHINXDIRS
> >> builds, because the root is the subdirectory in that case.
> >>
> >> Cc: Randy Dunlap <rdunlap@infradead.org>
> >> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> >> Cc: Jonathan Corbet <corbet@lwn.net>
> >> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
> >
> >
> >> diff --git a/Documentation/conf.py b/Documentation/conf.py
> >> index 574896cca198..b9a43ee32a00 100644
> >> --- a/Documentation/conf.py
> >> +++ b/Documentation/conf.py
> >> @@ -38,7 +38,7 @@ else:
> >> doctree = os.path.abspath(".")
> >>
> >> # Exclude of patterns that don't contain directory names, in glob format.
> >> -exclude_patterns = []
> >> +exclude_patterns = ['sphinx-includes/*']
> >
> > This doesn't work the way on might expect. The problem also affects
> > patch 4.
> >
> > Basically, when SUBDIRS is used, include and exclude patterns need
> > to be dynamically calculated, as, instead of building docs using
> >
> > Documentation/, the logic builds inside documentation/<directory>
> >
> > So, instead, you need to do:
> >
> > dyn_exclude_patterns.append("sphinx-includes/*")
> >
> > To ensure that it will pick just the right includes directory.
>
> Sphinx will only look for files within the source directory passed to
> sphinx-build. With SPHINXDIRS, the Documentation/ is not it. There's no
> need to specifically exclude anything that's outside of the source
> directory hierarchy.
>
> The whole dyn_exclude_patterns looks like overkill to me. It should just
> look at exclude_patterns, and remove anything that's outside of the
> SPHINXDIRS specified, and remove the SPHINXDIRS prefix from the
> remaining ones.
It is not overkill: this is needed to ensure that the patterns
will be applied the right way. See for instance those:
if has_include_patterns:
dyn_include_patterns.append("netlink/specs/*.yaml")
else:
dyn_exclude_patterns.append("netlink/*.yaml")
dyn_exclude_patterns.append("devicetree/bindings/**.yaml")
dyn_exclude_patterns.append("core-api/kho/bindings/**.yaml")
if one calls:
make SPHINXDIRS=netlink htmldocs
the path needs to be recalculated to drop "netlink/".
In the very specific case of your pattern, it depends if you're
storing it under Documentation/sphinx-includes or elsewhere.
--
Thanks,
Mauro
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 4/4] Documentation: use a source-read extension to include the index boilerplate
2025-11-13 8:12 ` Jani Nikula
@ 2025-11-13 10:25 ` Mauro Carvalho Chehab
2025-11-13 19:36 ` Randy Dunlap
1 sibling, 0 replies; 17+ messages in thread
From: Mauro Carvalho Chehab @ 2025-11-13 10:25 UTC (permalink / raw)
To: Jani Nikula
Cc: Mauro Carvalho Chehab, linux-doc, Randy Dunlap, Jonathan Corbet
On Thu, Nov 13, 2025 at 10:12:59AM +0200, Jani Nikula wrote:
> On Wed, 12 Nov 2025, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> > On Wed, Nov 12, 2025 at 01:56:54PM +0200, Jani Nikula wrote:
> >> Reduce boilerplate all over the place by adding a small ad hoc extension
> >> in conf.py that adds the ../sphinx-includes/subproject-index.rst include
> >> to all SPHINXDIRS builds.
> >>
> >> Note that the docname is just 'index', because the SPHINXDIRS builds
> >> happen in the subdirectories.
> >>
> >> Cc: Randy Dunlap <rdunlap@infradead.org>
> >> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> >> Cc: Jonathan Corbet <corbet@lwn.net>
> >> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
> >
> >> diff --git a/Documentation/conf.py b/Documentation/conf.py
> >> index b9a43ee32a00..cb0936a71d52 100644
> >> --- a/Documentation/conf.py
> >> +++ b/Documentation/conf.py
> >> @@ -589,8 +589,14 @@ kerneldoc_srctree = ".."
> >> # ------------------------------------------------------------------------------
> >> loadConfig(globals())
> >>
> >> +# Add index link to SPHINXDIRS builds
> >> +def add_subproject_index(app, docname, source):
> >> + if app.builder.tags.has('subproject') and app.builder.tags.has('html'):
> >> + if docname == 'index':
> >> + source[0] += '\n.. include:: ../sphinx-includes/subproject-index.rst\n'
> >
> > The relative path there breaks SPINXDIRS, when it is pointing to use a sub-sub-dir
> > like:
> >
> > $ make SPHINXDIRS=userspace-api/media htmldocs
>
> Ugh, I looked at 'make help' for the "valid values for SPHINXDIRS",
> which only lists the top level directories. Patch 1 is also based on
> this.
>
> What a surprise, the documentation for documentation is useless.
Yeah, _SPHINXDIRS helper message was introduced back in 2016
on this changeset:
606b9ac81a63 ("doc-rst: generic way to build only sphinx sub-folders")
On that time, we didn't have much things under Documentation/, so
the helper message makes sense. Also, each subsystem had its own top-level
directory. Nowadays, subsystem-specific documentation is typically under
Documentation/<core-api|driver-api|userspace-api|...>/<subsystem>
So, SPHINXDIRS is nowadays used to point to the second level directory
on lots of real use cases.
One needs to add an update there at the helper message.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 0/4] Documentation: clean up subproject index boilerplate
2025-11-12 11:56 [PATCH 0/4] Documentation: clean up subproject index boilerplate Jani Nikula
` (4 preceding siblings ...)
2025-11-13 6:50 ` [PATCH 0/4] Documentation: clean up subproject " Randy Dunlap
@ 2025-11-13 16:33 ` Jonathan Corbet
2025-11-13 16:59 ` Jani Nikula
5 siblings, 1 reply; 17+ messages in thread
From: Jonathan Corbet @ 2025-11-13 16:33 UTC (permalink / raw)
To: Jani Nikula, linux-doc; +Cc: jani.nikula
Jani Nikula <jani.nikula@intel.com> writes:
> Only very lightly tested.
>
> Jani Nikula (4):
> Documentation: remove subproject index links deep in the structure
> Documentation: streamline subproject index link in translations
> Documentation: include the boilerplate for SPHINXDIRS index link
> Documentation: use a source-read extension to include the index
> boilerplate
That bit of repeated gunk has been on my list to look at for a while,
thanks for digging into it. Looking forward to the second version.
Thanks,
jon
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 0/4] Documentation: clean up subproject index boilerplate
2025-11-13 16:33 ` Jonathan Corbet
@ 2025-11-13 16:59 ` Jani Nikula
2025-12-04 13:43 ` Jani Nikula
0 siblings, 1 reply; 17+ messages in thread
From: Jani Nikula @ 2025-11-13 16:59 UTC (permalink / raw)
To: Jonathan Corbet, linux-doc
On Thu, 13 Nov 2025, Jonathan Corbet <corbet@lwn.net> wrote:
> Jani Nikula <jani.nikula@intel.com> writes:
>
>> Only very lightly tested.
>>
>> Jani Nikula (4):
>> Documentation: remove subproject index links deep in the structure
>> Documentation: streamline subproject index link in translations
>> Documentation: include the boilerplate for SPHINXDIRS index link
>> Documentation: use a source-read extension to include the index
>> boilerplate
>
> That bit of repeated gunk has been on my list to look at for a while,
> thanks for digging into it. Looking forward to the second version.
As I said elsewhere, I didn't realize you could use SPHINXDIRS deeper
than the top level. The implementation is slightly problematic for
translations/. I don't suppose you want to have English "Indices"
heading when using, say, SPHINXDIRS=translations/it_IT/doc-guide?
I guess the alternatives are:
1) Keep having the index links manually in translations/, and don't add
the template for files there.
2) Accept English "Indices" as a tradeoff.
3) Come up with a system of having multiple language templates for the
indices, and use them automatically under translations/.
We could also do 2) first and expand to 3) later.
BR,
Jani.
--
Jani Nikula, Intel
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 4/4] Documentation: use a source-read extension to include the index boilerplate
2025-11-13 8:12 ` Jani Nikula
2025-11-13 10:25 ` Mauro Carvalho Chehab
@ 2025-11-13 19:36 ` Randy Dunlap
1 sibling, 0 replies; 17+ messages in thread
From: Randy Dunlap @ 2025-11-13 19:36 UTC (permalink / raw)
To: Jani Nikula, Mauro Carvalho Chehab; +Cc: linux-doc, Jonathan Corbet
On 11/13/25 12:12 AM, Jani Nikula wrote:
> On Wed, 12 Nov 2025, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
>> On Wed, Nov 12, 2025 at 01:56:54PM +0200, Jani Nikula wrote:
>>> Reduce boilerplate all over the place by adding a small ad hoc extension
>>> in conf.py that adds the ../sphinx-includes/subproject-index.rst include
>>> to all SPHINXDIRS builds.
>>>
>>> Note that the docname is just 'index', because the SPHINXDIRS builds
>>> happen in the subdirectories.
>>>
>>> Cc: Randy Dunlap <rdunlap@infradead.org>
>>> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>>> Cc: Jonathan Corbet <corbet@lwn.net>
>>> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
>>
>>> diff --git a/Documentation/conf.py b/Documentation/conf.py
>>> index b9a43ee32a00..cb0936a71d52 100644
>>> --- a/Documentation/conf.py
>>> +++ b/Documentation/conf.py
>>> @@ -589,8 +589,14 @@ kerneldoc_srctree = ".."
>>> # ------------------------------------------------------------------------------
>>> loadConfig(globals())
>>>
>>> +# Add index link to SPHINXDIRS builds
>>> +def add_subproject_index(app, docname, source):
>>> + if app.builder.tags.has('subproject') and app.builder.tags.has('html'):
>>> + if docname == 'index':
>>> + source[0] += '\n.. include:: ../sphinx-includes/subproject-index.rst\n'
>>
>> The relative path there breaks SPINXDIRS, when it is pointing to use a sub-sub-dir
>> like:
>>
>> $ make SPHINXDIRS=userspace-api/media htmldocs
>
> Ugh, I looked at 'make help' for the "valid values for SPHINXDIRS",
> which only lists the top level directories. Patch 1 is also based on
> this.
>
> What a surprise, the documentation for documentation is useless.
Yeah, I only found out recently that subdirs can be specified there.
--
~Randy
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 0/4] Documentation: clean up subproject index boilerplate
2025-11-13 16:59 ` Jani Nikula
@ 2025-12-04 13:43 ` Jani Nikula
0 siblings, 0 replies; 17+ messages in thread
From: Jani Nikula @ 2025-12-04 13:43 UTC (permalink / raw)
To: Jonathan Corbet, linux-doc
On Thu, 13 Nov 2025, Jani Nikula <jani.nikula@intel.com> wrote:
> On Thu, 13 Nov 2025, Jonathan Corbet <corbet@lwn.net> wrote:
>> Jani Nikula <jani.nikula@intel.com> writes:
>>
>>> Only very lightly tested.
>>>
>>> Jani Nikula (4):
>>> Documentation: remove subproject index links deep in the structure
>>> Documentation: streamline subproject index link in translations
>>> Documentation: include the boilerplate for SPHINXDIRS index link
>>> Documentation: use a source-read extension to include the index
>>> boilerplate
>>
>> That bit of repeated gunk has been on my list to look at for a while,
>> thanks for digging into it. Looking forward to the second version.
>
> As I said elsewhere, I didn't realize you could use SPHINXDIRS deeper
> than the top level. The implementation is slightly problematic for
> translations/. I don't suppose you want to have English "Indices"
> heading when using, say, SPHINXDIRS=translations/it_IT/doc-guide?
>
> I guess the alternatives are:
>
> 1) Keep having the index links manually in translations/, and don't add
> the template for files there.
>
> 2) Accept English "Indices" as a tradeoff.
>
> 3) Come up with a system of having multiple language templates for the
> indices, and use them automatically under translations/.
>
> We could also do 2) first and expand to 3) later.
Jon, any input on this?
BR,
Jani.
--
Jani Nikula, Intel
^ permalink raw reply [flat|nested] 17+ messages in thread
end of thread, other threads:[~2025-12-04 13:43 UTC | newest]
Thread overview: 17+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2025-11-12 11:56 [PATCH 0/4] Documentation: clean up subproject index boilerplate Jani Nikula
2025-11-12 11:56 ` [PATCH 1/4] Documentation: remove subproject index links deep in the structure Jani Nikula
2025-11-12 13:27 ` Mauro Carvalho Chehab
2025-11-12 11:56 ` [PATCH 2/4] Documentation: streamline subproject index link in translations Jani Nikula
2025-11-12 11:56 ` [PATCH 3/4] Documentation: include the boilerplate for SPHINXDIRS index link Jani Nikula
2025-11-12 13:35 ` Mauro Carvalho Chehab
2025-11-13 8:04 ` Jani Nikula
2025-11-13 10:11 ` Mauro Carvalho Chehab
2025-11-12 11:56 ` [PATCH 4/4] Documentation: use a source-read extension to include the index boilerplate Jani Nikula
2025-11-12 13:39 ` Mauro Carvalho Chehab
2025-11-13 8:12 ` Jani Nikula
2025-11-13 10:25 ` Mauro Carvalho Chehab
2025-11-13 19:36 ` Randy Dunlap
2025-11-13 6:50 ` [PATCH 0/4] Documentation: clean up subproject " Randy Dunlap
2025-11-13 16:33 ` Jonathan Corbet
2025-11-13 16:59 ` Jani Nikula
2025-12-04 13:43 ` Jani Nikula
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).