Documentation: use a source-read extension for the index link boilerplate

The root document usually has a special :ref:`genindex` link to the
generated index. This is also the case for Documentation/index.rst. The
other index.rst files deeper in the directory hierarchy usually don't.

For SPHINXDIRS builds, the root document isn't Documentation/index.rst,
but some other index.rst in the hierarchy. Currently they have a
".. only::" block to add the index link when doing SPHINXDIRS html
builds.

This is obviously very tedious and repetitive. The link is also added to
all index.rst files in the hierarchy for SPHINXDIRS builds, not just the
root document.

Put the boilerplate in a sphinx-includes/subproject-index.rst file, and
include it at the end of the root document for subproject builds in an
ad-hoc source-read extension defined in conf.py.

For now, keep having the boilerplate in translations, because this
approach currently doesn't cover translated index link headers.

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Tested-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
[jc: did s/doctree/kern_doc_dir/ ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260123143149.2024303-1-jani.nikula@intel.com>
This commit is contained in:
Jani Nikula 2026-01-23 16:31:49 +02:00 committed by Jonathan Corbet
parent 330367bdc1
commit a592a36e49
101 changed files with 31 additions and 685 deletions

View File

@ -28,10 +28,3 @@ RCU Handbook
Design/Expedited-Grace-Periods/Expedited-Grace-Periods Design/Expedited-Grace-Periods/Expedited-Grace-Periods
Design/Requirements/Requirements Design/Requirements/Requirements
Design/Data-Structures/Data-Structures Design/Data-Structures/Data-Structures
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -11,10 +11,3 @@ Compute Accelerators
amdxdna/index amdxdna/index
qaic/index qaic/index
rocket/index rocket/index
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -8,10 +8,3 @@ ATA over Ethernet (AoE)
aoe aoe
todo todo
examples examples
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -7,10 +7,3 @@ Auxiliary Display Support
ks0108.rst ks0108.rst
cfag12864b.rst cfag12864b.rst
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -22,10 +22,3 @@ Control Groups version 1
net_prio net_prio
pids pids
rdma rdma
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -12,10 +12,3 @@ CIFS
todo todo
changes changes
authors authors
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -40,10 +40,3 @@ Device Mapper
verity verity
writecache writecache
zero zero
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -12,10 +12,3 @@ GPIO
gpio-sim gpio-sim
gpio-virtuser gpio-virtuser
Obsolete APIs <obsolete> Obsolete APIs <obsolete>
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -189,10 +189,3 @@ A few hard-to-categorize and generally obsolete documents.
ldm ldm
unicode unicode
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -11,10 +11,3 @@ information.
kdump kdump
vmcoreinfo vmcoreinfo
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -8,10 +8,3 @@ ARC architecture
arc arc
features features
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -75,11 +75,3 @@ SoC-specific documents
sti/overview sti/overview
vfp/release-notes vfp/release-notes
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -33,10 +33,3 @@ ARM64 Architecture
tagged-pointers tagged-pointers
features features
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -13,10 +13,3 @@ LoongArch Architecture
irq-chip-model irq-chip-model
features features
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -11,10 +11,3 @@ m68k Architecture
buddha-driver buddha-driver
features features
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -12,10 +12,3 @@ MIPS-specific Documentation
ingenic-tcu ingenic-tcu
features features
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -11,10 +11,3 @@ OpenRISC Architecture
todo todo
features features
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -11,10 +11,3 @@ PA-RISC Architecture
registers registers
features features
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -40,10 +40,3 @@ powerpc
vpa-dtl vpa-dtl
features features
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -16,10 +16,3 @@ RISC-V architecture
cmodx cmodx
features features
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -22,10 +22,3 @@ s390 Architecture
text_files text_files
features features
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -34,12 +34,5 @@ that goes into great technical depth about the BPF Architecture.
other other
redirect redirect
.. only:: subproject and html
Indices
=======
* :ref:`genindex`
.. Links: .. Links:
.. _BPF and XDP Reference Guide: https://docs.cilium.io/en/latest/bpf/ .. _BPF and XDP Reference Guide: https://docs.cilium.io/en/latest/bpf/

View File

@ -8,10 +8,3 @@ CD-ROM
:maxdepth: 1 :maxdepth: 1
cdrom-standard cdrom-standard
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -42,7 +42,7 @@ exclude_patterns = []
# List of patterns that contain directory names in glob format. # List of patterns that contain directory names in glob format.
dyn_include_patterns = [] dyn_include_patterns = []
dyn_exclude_patterns = ["output"] dyn_exclude_patterns = ["output", "sphinx-includes"]
# Currently, only netlink/specs has a parser for yaml. # Currently, only netlink/specs has a parser for yaml.
# Prefer using include patterns if available, as it is faster # Prefer using include patterns if available, as it is faster
@ -587,7 +587,30 @@ pdf_documents = [
kerneldoc_srctree = ".." kerneldoc_srctree = ".."
# Add index link at the end of the root document for SPHINXDIRS builds.
def add_subproject_index(app, docname, content):
# Only care about root documents
if docname != master_doc:
return
# Add the index link at the root of translations, but not at the root of
# individual translations. They have their own language specific links.
rel = os.path.relpath(app.srcdir, start=kern_doc_dir).split('/')
if rel[0] == 'translations' and len(rel) > 1:
return
# Only add the link for SPHINXDIRS HTML builds
if not app.builder.tags.has('subproject') or not app.builder.tags.has('html'):
return
# The include directive needs a relative path from the srcdir
rel = os.path.relpath(os.path.join(kern_doc_dir, 'sphinx-includes/subproject-index.rst'),
start=app.srcdir)
content[0] += f'\n.. include:: {rel}\n\n'
def setup(app): def setup(app):
"""Patterns need to be updated at init time on older Sphinx versions""" """Patterns need to be updated at init time on older Sphinx versions"""
app.connect('config-inited', config_init) app.connect('config-inited', config_init)
app.connect('source-read', add_subproject_index)

View File

@ -140,10 +140,3 @@ Documents that don't fit elsewhere or which have yet to be categorized.
librs librs
liveupdate liveupdate
netlink netlink
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -9,5 +9,3 @@ Kexec Handover Subsystem
concepts concepts
fdt fdt
.. only:: subproject and html

View File

@ -38,11 +38,3 @@ Documentation/process/debugging/index.rst
gpio-sloppy-logic-analyzer gpio-sloppy-logic-analyzer
autofdo autofdo
propeller propeller
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -13,10 +13,3 @@ How to write kernel documentation
contributing contributing
maintainer-profile maintainer-profile
checktransupdate checktransupdate
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -8,10 +8,3 @@ Linux 802.11 Driver Developer's Guide
cfg80211 cfg80211
mac80211 mac80211
mac80211-advanced mac80211-advanced
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -8,5 +8,3 @@ Confidential Computing
:maxdepth: 1 :maxdepth: 1
measurement-registers measurement-registers
.. only:: subproject and html

View File

@ -11,10 +11,3 @@ API.
:maxdepth: 1 :maxdepth: 1
iaa-crypto iaa-crypto
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -11,10 +11,3 @@ configuration.
:maxdepth: 1 :maxdepth: 1
iaa/index iaa/index
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -50,5 +50,3 @@ that have impacts on each other. The docs here break up configurations steps.
allocation/page-allocator allocation/page-allocator
allocation/reclaim allocation/reclaim
allocation/hugepages.rst allocation/hugepages.rst
.. only:: subproject and html

View File

@ -46,10 +46,3 @@ This book adds some notes about PXA DMA
:maxdepth: 1 :maxdepth: 1
pxa_dma pxa_dma
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -14,10 +14,3 @@ Driver Model
overview overview
platform platform
porting porting
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -9,10 +9,3 @@ Early Userspace
early_userspace_support early_userspace_support
buffer-format buffer-format
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -10,10 +10,3 @@ Linux Firmware API
request_firmware request_firmware
fw_upload fw_upload
other_interfaces other_interfaces
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -149,10 +149,3 @@ Subsystem-specific APIs
wmi wmi
xilinx/index xilinx/index
zorro zorro
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -9,10 +9,3 @@ Memory Controller drivers
ti-emif ti-emif
ti-gpmc ti-gpmc
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -11,10 +11,3 @@ The Linux PCI driver implementer's API guide
pci pci
p2pdma p2pdma
tsm tsm
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -8,11 +8,3 @@ Generic PHY Framework
phy phy
samsung-usb2 samsung-usb2
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -10,10 +10,3 @@ CPU and Device Power Management
devices devices
notifiers notifiers
types types
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -18,10 +18,3 @@ Serial drivers
serial-iso7816 serial-iso7816
serial-rs485 serial-rs485
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -11,10 +11,3 @@ SoundWire Documentation
locking locking
bra bra
bra_cadence bra_cadence
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -14,10 +14,3 @@ on how to write client drivers.
cdev cdev
dtx dtx
san san
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -12,10 +12,3 @@ Surface System Aggregator Module (SSAM)
clients/index clients/index
ssh ssh
internal internal
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -22,10 +22,3 @@ Linux USB API
typec typec
typec_bus typec_bus
usb3-debug-port usb3-debug-port
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -7,10 +7,3 @@ Xilinx FPGA
:maxdepth: 1 :maxdepth: 1
eemi eemi
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -11,10 +11,3 @@ Fault-injection
notifier-error-inject notifier-error-inject
nvme-fault-injection nvme-fault-injection
provoke-crashes provoke-crashes
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -50,10 +50,3 @@ Driver documentation
vesafb vesafb
viafb viafb
vt8623fb vt8623fb
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -8,10 +8,3 @@ FPGA
:maxdepth: 1 :maxdepth: 1
dfl dfl
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -26,10 +26,3 @@ GPU Driver Documentation
panthor panthor
zynqmp zynqmp
nova/index nova/index
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -22,10 +22,3 @@ GPU Driver Developer's Guide
implementation_guidelines implementation_guidelines
todo todo
rfc/index rfc/index
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -281,10 +281,3 @@ Hardware Monitoring Kernel Drivers
xdpe12284 xdpe12284
xdpe152c4 xdpe152c4
zl6100 zl6100
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -66,10 +66,3 @@ Legacy documentation
:maxdepth: 1 :maxdepth: 1
old-module-parameters old-module-parameters
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -15,10 +15,3 @@ InfiniBand
ucaps ucaps
user_mad user_mad
user_verbs user_verbs
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -10,10 +10,3 @@ Linux kernel, their protocols, and driver details.
:glob: :glob:
* *
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -10,10 +10,3 @@ Contents:
input_uapi input_uapi
input_kapi input_kapi
devices/index devices/index
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -12,10 +12,3 @@ ISDN
m_isdn m_isdn
credits credits
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -24,10 +24,3 @@ Kernel Build System
gendwarfksyms gendwarfksyms
bash-completion bash-completion
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -15,10 +15,3 @@ Kernel Livepatching
system-state system-state
reliable-stacktrace reliable-stacktrace
api api
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -24,10 +24,3 @@ Locking
percpu-rw-semaphore percpu-rw-semaphore
robust-futexes robust-futexes
robust-futex-ABI robust-futex-ABI
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -9,10 +9,3 @@ MHI
mhi mhi
topology topology
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -12,10 +12,3 @@ NetLabel
lsm_interface lsm_interface
draft_ietf draft_ietf
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -11,10 +11,3 @@ Contents:
cxacru cxacru
fore200e fore200e
iphase iphase
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -13,10 +13,3 @@ Contents:
can327 can327
ctu/ctucanfd-driver ctu/ctucanfd-driver
freescale/flexcan freescale/flexcan
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -9,10 +9,3 @@ Contents:
:maxdepth: 2 :maxdepth: 2
qualcomm/rmnet qualcomm/rmnet
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -64,10 +64,3 @@ Contents:
wangxun/txgbevf wangxun/txgbevf
wangxun/ngbe wangxun/ngbe
wangxun/ngbevf wangxun/ngbevf
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -16,10 +16,3 @@ Contents:
switchdev switchdev
tracepoints tracepoints
counters counters
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -10,10 +10,3 @@ Contents:
defza defza
skfp skfp
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -10,10 +10,3 @@ Contents:
baycom baycom
z8530drv z8530drv
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -16,10 +16,3 @@ Contents:
hamradio/index hamradio/index
wifi/index wifi/index
wwan/index wwan/index
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -10,10 +10,3 @@ Contents:
intel/ipw2100 intel/ipw2100
intel/ipw2200 intel/ipw2200
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -10,10 +10,3 @@ Contents:
iosm iosm
t7xx t7xx
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -8,10 +8,3 @@ Networking Diagnostics
:maxdepth: 2 :maxdepth: 2
twisted_pair_layer1_diagnostics.rst twisted_pair_layer1_diagnostics.rst
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -134,10 +134,3 @@ Contents:
xfrm/index xfrm/index
xdp-rx-metadata xdp-rx-metadata
xsk-tx-metadata xsk-tx-metadata
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -11,10 +11,3 @@ PCMCIA
devicetable devicetable
locking locking
driver-changes driver-changes
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -7,10 +7,3 @@ PECI Subsystem
.. toctree:: .. toctree::
peci peci
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -38,10 +38,3 @@ Power Management
regulator/machine regulator/machine
regulator/overview regulator/overview
regulator/regulator regulator/regulator
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -15,8 +15,6 @@ general guides
kgdb kgdb
userspace_debugging_guide userspace_debugging_guide
.. only:: subproject and html
subsystem specific guides subsystem specific guides
------------------------- -------------------------
@ -25,13 +23,6 @@ subsystem specific guides
media_specific_debugging_guide media_specific_debugging_guide
.. only:: subproject and html
Indices
=======
* :ref:`genindex`
General debugging advice General debugging advice
======================== ========================

View File

@ -110,10 +110,3 @@ developers:
kernel-docs kernel-docs
deprecated deprecated
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -58,10 +58,3 @@ more details.
You can also find learning materials for Rust in its section in You can also find learning materials for Rust in its section in
:doc:`../process/kernel-docs`. :doc:`../process/kernel-docs`.
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -25,10 +25,3 @@ Scheduler
sched-debug sched-debug
text_files text_files
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -15,10 +15,3 @@ Sound Subsystem Documentation
cards/index cards/index
codecs/index codecs/index
utimers utimers
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -0,0 +1,7 @@
.. SPDX-License-Identifier: GPL-2.0
.. This file is included in subproject root documents in conf.py
Indices
=======
* :ref:`genindex`

View File

@ -12,10 +12,3 @@ Serial Peripheral Interface (SPI)
butterfly butterfly
spi-lm70llp spi-lm70llp
spi-sc18is602 spi-sc18is602
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -10,10 +10,3 @@ TCM Virtual Device
tcmu-design tcmu-design
tcm_mod_builder tcm_mod_builder
scripts scripts
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -12,10 +12,3 @@ TEE Subsystem
amd-tee amd-tee
ts-tee ts-tee
qtee qtee
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -13,10 +13,3 @@ Timers
no_hz no_hz
timekeeping timekeeping
delay_sleep_functions delay_sleep_functions
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -13,10 +13,3 @@ more additions are needed here:
rtla/index rtla/index
rv/index rv/index
python python
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -18,10 +18,3 @@ behavior on specific hardware.
rtla-timerlat-hist rtla-timerlat-hist
rtla-timerlat-top rtla-timerlat-top
rtla-hwnoise rtla-hwnoise
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -16,10 +16,3 @@ Runtime verification (rv) tool
rv-mon-wip rv-mon-wip
rv-mon-wwnr rv-mon-wwnr
rv-mon-sched rv-mon-sched
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -95,10 +95,3 @@ Additional Resources
For more details, refer to the respective documentation of each For more details, refer to the respective documentation of each
tracing tool and framework. tracing tool and framework.
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -31,10 +31,3 @@ USB support
usb-help usb-help
text_files text_files
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -9,10 +9,3 @@ GPIO
Character Device Userspace API <chardev> Character Device Userspace API <chardev>
Obsolete Userspace APIs <obsolete> Obsolete Userspace APIs <obsolete>
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -68,10 +68,3 @@ Everything else
futex2 futex2
perf_ring_buffer perf_ring_buffer
ntsync ntsync
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -16,10 +16,3 @@ Virtualization Support
coco/sev-guest coco/sev-guest
coco/tdx-guest coco/tdx-guest
hyperv/index hyperv/index
.. only:: html and subproject
Indices
=======
* :ref:`genindex`

View File

@ -12,10 +12,3 @@
w1-netlink.rst w1-netlink.rst
masters/index masters/index
slaves/index slaves/index
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -16,10 +16,3 @@ Watchdog Support
watchdog-pm watchdog-pm
wdt wdt
convert_drivers_to_kernel_api convert_drivers_to_kernel_api
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -13,10 +13,3 @@ the Linux kernel, their protocols and driver details.
:glob: :glob:
* *
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

Some files were not shown because too many files have changed in this diff Show More