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>
Design/Expedited-Grace-Periods/Expedited-Grace-Periods
Design/Requirements/Requirements
Design/Data-Structures/Data-Structures
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
amdxdna/index
qaic/index
rocket/index
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
aoe
todo
examples
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
ks0108.rst
cfag12864b.rst
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
net_prio
pids
rdma
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
todo
changes
authors
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
verity
writecache
zero
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
gpio-sim
gpio-virtuser
Obsolete APIs <obsolete>
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
ldm
unicode
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
kdump
vmcoreinfo
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
arc
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
sti/overview
vfp/release-notes
-
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
tagged-pointers
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
irq-chip-model
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
buddha-driver
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
ingenic-tcu
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
todo
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
registers
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
vpa-dtl
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
cmodx
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
text_files
features
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
other
redirect
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
-
.. Links:
.. _BPF and XDP Reference Guide: https://docs.cilium.io/en/latest/bpf/
:maxdepth: 1
cdrom-standard
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
# 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
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)
librs
liveupdate
netlink
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
concepts
fdt
-
-.. only:: subproject and html
gpio-sloppy-logic-analyzer
autofdo
propeller
-
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
contributing
maintainer-profile
checktransupdate
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
cfg80211
mac80211
mac80211-advanced
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
:maxdepth: 1
measurement-registers
-
-.. only:: subproject and html
:maxdepth: 1
iaa-crypto
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
:maxdepth: 1
iaa/index
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
allocation/page-allocator
allocation/reclaim
allocation/hugepages.rst
-
-.. only:: subproject and html
:maxdepth: 1
pxa_dma
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
overview
platform
porting
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
early_userspace_support
buffer-format
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
request_firmware
fw_upload
other_interfaces
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
wmi
xilinx/index
zorro
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
ti-emif
ti-gpmc
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
pci
p2pdma
tsm
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
phy
samsung-usb2
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
-
devices
notifiers
types
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
serial-iso7816
serial-rs485
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
locking
bra
bra_cadence
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
cdev
dtx
san
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
clients/index
ssh
internal
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
typec
typec_bus
usb3-debug-port
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
:maxdepth: 1
eemi
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
notifier-error-inject
nvme-fault-injection
provoke-crashes
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
vesafb
viafb
vt8623fb
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
:maxdepth: 1
dfl
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
panthor
zynqmp
nova/index
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
implementation_guidelines
todo
rfc/index
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
xdpe12284
xdpe152c4
zl6100
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
:maxdepth: 1
old-module-parameters
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
ucaps
user_mad
user_verbs
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
:glob:
*
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
input_uapi
input_kapi
devices/index
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
m_isdn
credits
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
gendwarfksyms
bash-completion
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
system-state
reliable-stacktrace
api
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
percpu-rw-semaphore
robust-futexes
robust-futex-ABI
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
mhi
topology
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
lsm_interface
draft_ietf
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
cxacru
fore200e
iphase
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
can327
ctu/ctucanfd-driver
freescale/flexcan
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
:maxdepth: 2
qualcomm/rmnet
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
wangxun/txgbevf
wangxun/ngbe
wangxun/ngbevf
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
switchdev
tracepoints
counters
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
defza
skfp
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
baycom
z8530drv
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
hamradio/index
wifi/index
wwan/index
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
intel/ipw2100
intel/ipw2200
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
iosm
t7xx
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
:maxdepth: 2
twisted_pair_layer1_diagnostics.rst
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
xfrm/index
xdp-rx-metadata
xsk-tx-metadata
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
devicetable
locking
driver-changes
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
.. toctree::
peci
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
regulator/machine
regulator/overview
regulator/regulator
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
kgdb
userspace_debugging_guide
-.. only:: subproject and html
-
subsystem specific guides
-------------------------
media_specific_debugging_guide
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
-
General debugging advice
========================
kernel-docs
deprecated
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
You can also find learning materials for Rust in its section in
:doc:`../process/kernel-docs`.
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
sched-debug
text_files
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
cards/index
codecs/index
utimers
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0
+.. This file is included in subproject root documents in conf.py
+
+Indices
+=======
+
+* :ref:`genindex`
butterfly
spi-lm70llp
spi-sc18is602
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
tcmu-design
tcm_mod_builder
scripts
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
amd-tee
ts-tee
qtee
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
no_hz
timekeeping
delay_sleep_functions
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
rtla/index
rv/index
python
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
rtla-timerlat-hist
rtla-timerlat-top
rtla-hwnoise
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
rv-mon-wip
rv-mon-wwnr
rv-mon-sched
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
For more details, refer to the respective documentation of each
tracing tool and framework.
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
usb-help
text_files
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
Character Device Userspace API <chardev>
Obsolete Userspace APIs <obsolete>
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
futex2
perf_ring_buffer
ntsync
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
coco/sev-guest
coco/tdx-guest
hyperv/index
-
-.. only:: html and subproject
-
- Indices
- =======
-
- * :ref:`genindex`
w1-netlink.rst
masters/index
slaves/index
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
watchdog-pm
wdt
convert_drivers_to_kernel_api
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
:glob:
*
-
-.. only:: subproject and html
-
- Indices
- =======
-
- * :ref:`genindex`
acpi-interface
driver-development-guide
devices/index
-
-.. only:: subproject and html
-
-
- Indices
- =======
-
- * :ref:`genindex`