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/Requirements/Requirements
Design/Data-Structures/Data-Structures
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

@ -12,10 +12,3 @@ GPIO
gpio-sim
gpio-virtuser
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
unicode
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

@ -22,10 +22,3 @@ s390 Architecture
text_files
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
redirect
.. only:: subproject and html
Indices
=======
* :ref:`genindex`
.. Links:
.. _BPF and XDP Reference Guide: https://docs.cilium.io/en/latest/bpf/

View file

@ -8,10 +8,3 @@ CD-ROM
:maxdepth: 1
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.
dyn_include_patterns = []
dyn_exclude_patterns = ["output"]
dyn_exclude_patterns = ["output", "sphinx-includes"]
# Currently, only netlink/specs has a parser for yaml.
# Prefer using include patterns if available, as it is faster
@ -587,7 +587,30 @@ pdf_documents = [
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):
"""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)

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

@ -11,10 +11,3 @@ configuration.
:maxdepth: 1
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/reclaim
allocation/hugepages.rst
.. only:: subproject and html

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

@ -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
========================

View file

@ -110,10 +110,3 @@ developers:
kernel-docs
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
:doc:`../process/kernel-docs`.
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View file

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

View file

@ -15,10 +15,3 @@ Sound Subsystem Documentation
cards/index
codecs/index
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
spi-lm70llp
spi-sc18is602
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View file

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

View file

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

View file

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

View file

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

View file

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

View file

@ -16,10 +16,3 @@ Runtime verification (rv) tool
rv-mon-wip
rv-mon-wwnr
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
tracing tool and framework.
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View file

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

View file

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

View file

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

View file

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

View file

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

View file

@ -16,10 +16,3 @@ Watchdog Support
watchdog-pm
wdt
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:
*
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

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