Documentation: clean up subproject index boilerplate
Subsystems (65)
cover Documentation: clean up subproject index boilerplate
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
Signature · 1 line
2.47.3
PATCH 1/4 Documentation: remove subproject index links deep in the structure
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 <[email protected]>
Cc Mauro Carvalho Chehab <[email protected]>
Cc Jonathan Corbet <[email protected]>
Signed-off-by Jani Nikula <[email protected]>
--- 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(-)
Documentation/admin-guide/aoe/index.rst +0 -7
@@ -8,10 +8,3 @@ ATA over Ethernet (AoE) aoe todo examples - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/admin-guide/auxdisplay/index.rst +0 -7
@@ -7,10 +7,3 @@ Auxiliary Display Support ks0108.rst cfag12864b.rst - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/admin-guide/cgroup-v1/index.rst +0 -7
@@ -22,10 +22,3 @@ Control Groups version 1 net_prio pids rdma - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/admin-guide/cifs/index.rst +0 -7
@@ -12,10 +12,3 @@ CIFS todo changes authors - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/admin-guide/device-mapper/index.rst +0 -7
@@ -40,10 +40,3 @@ Device Mapper verity writecache zero - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/admin-guide/gpio/index.rst +0 -7
@@ -12,10 +12,3 @@ GPIO gpio-sim gpio-virtuser Obsolete APIs <obsolete> - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/admin-guide/kdump/index.rst +0 -7
@@ -11,10 +11,3 @@ information. kdump vmcoreinfo - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/arch/arc/index.rst +0 -7
@@ -8,10 +8,3 @@ ARC architecture arc features - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/arch/arm/index.rst +0 -8
@@ -75,11 +75,3 @@ SoC-specific documents sti/overview vfp/release-notes - - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/arch/arm64/index.rst +0 -7
@@ -33,10 +33,3 @@ ARM64 Architecture tagged-pointers features - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/arch/loongarch/index.rst +0 -7
@@ -13,10 +13,3 @@ LoongArch Architecture irq-chip-model features - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/arch/m68k/index.rst +0 -7
@@ -11,10 +11,3 @@ m68k Architecture buddha-driver features - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/arch/mips/index.rst +0 -7
@@ -12,10 +12,3 @@ MIPS-specific Documentation ingenic-tcu features - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/arch/openrisc/index.rst +0 -7
@@ -11,10 +11,3 @@ OpenRISC Architecture todo features - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/arch/parisc/index.rst +0 -7
@@ -11,10 +11,3 @@ PA-RISC Architecture registers features - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/arch/powerpc/index.rst +0 -7
@@ -40,10 +40,3 @@ powerpc vpa-dtl features - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/arch/riscv/index.rst +0 -7
@@ -16,10 +16,3 @@ RISC-V architecture cmodx features - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/arch/s390/index.rst +0 -7
@@ -22,10 +22,3 @@ s390 Architecture text_files features - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/core-api/kho/index.rst +0 -2
@@ -9,5 +9,3 @@ Kexec Handover Subsystem concepts fdt - -.. only:: subproject and html
Documentation/driver-api/80211/index.rst +0 -7
@@ -8,10 +8,3 @@ Linux 802.11 Driver Developer's Guide cfg80211 mac80211 mac80211-advanced - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/driver-api/coco/index.rst +0 -2
@@ -8,5 +8,3 @@ Confidential Computing :maxdepth: 1 measurement-registers - -.. only:: subproject and html
Documentation/driver-api/crypto/iaa/index.rst +0 -7
@@ -11,10 +11,3 @@ API. :maxdepth: 1 iaa-crypto - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/driver-api/crypto/index.rst +0 -7
@@ -11,10 +11,3 @@ configuration. :maxdepth: 1 iaa/index - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/driver-api/cxl/index.rst +0 -2
@@ -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
Documentation/driver-api/dmaengine/index.rst +0 -7
@@ -46,10 +46,3 @@ This book adds some notes about PXA DMA :maxdepth: 1 pxa_dma - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/driver-api/driver-model/index.rst +0 -7
@@ -14,10 +14,3 @@ Driver Model overview platform porting - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/driver-api/early-userspace/index.rst +0 -7
@@ -9,10 +9,3 @@ Early Userspace early_userspace_support buffer-format - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/driver-api/firmware/index.rst +0 -7
@@ -10,10 +10,3 @@ Linux Firmware API request_firmware fw_upload other_interfaces - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/driver-api/memory-devices/index.rst +0 -7
@@ -9,10 +9,3 @@ Memory Controller drivers ti-emif ti-gpmc - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/driver-api/pci/index.rst +0 -7
@@ -10,10 +10,3 @@ The Linux PCI driver implementer's API guide pci p2pdma - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/driver-api/phy/index.rst +0 -8
@@ -8,11 +8,3 @@ Generic PHY Framework phy samsung-usb2 - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` -
Documentation/driver-api/pm/index.rst +0 -7
@@ -10,10 +10,3 @@ CPU and Device Power Management devices notifiers types - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/driver-api/serial/index.rst +0 -7
@@ -18,10 +18,3 @@ Serial drivers serial-iso7816 serial-rs485 - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/driver-api/soundwire/index.rst +0 -7
@@ -11,10 +11,3 @@ SoundWire Documentation locking bra bra_cadence - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/driver-api/surface_aggregator/clients/index.rst +0 -7
@@ -14,10 +14,3 @@ on how to write client drivers. cdev dtx san - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/driver-api/surface_aggregator/index.rst +0 -7
@@ -12,10 +12,3 @@ Surface System Aggregator Module (SSAM) clients/index ssh internal - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/driver-api/usb/index.rst +0 -7
@@ -22,10 +22,3 @@ Linux USB API typec typec_bus usb3-debug-port - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/driver-api/xilinx/index.rst +0 -7
@@ -7,10 +7,3 @@ Xilinx FPGA :maxdepth: 1 eemi - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/input/devices/index.rst +0 -7
@@ -10,10 +10,3 @@ Linux kernel, their protocols, and driver details. :glob: * - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/networking/device_drivers/atm/index.rst +0 -7
@@ -11,10 +11,3 @@ Contents: cxacru fore200e iphase - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/networking/device_drivers/can/index.rst +0 -7
@@ -13,10 +13,3 @@ Contents: can327 ctu/ctucanfd-driver freescale/flexcan - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/networking/device_drivers/cellular/index.rst +0 -7
@@ -9,10 +9,3 @@ Contents: :maxdepth: 2 qualcomm/rmnet - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/networking/device_drivers/ethernet/index.rst +0 -7
@@ -63,10 +63,3 @@ Contents: wangxun/txgbevf wangxun/ngbe wangxun/ngbevf - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/networking/device_drivers/ethernet/mellanox/mlx5/index.rst +0 -7
@@ -16,10 +16,3 @@ Contents: switchdev tracepoints counters - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/networking/device_drivers/fddi/index.rst +0 -7
@@ -10,10 +10,3 @@ Contents: defza skfp - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/networking/device_drivers/hamradio/index.rst +0 -7
@@ -10,10 +10,3 @@ Contents: baycom z8530drv - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/networking/device_drivers/index.rst +0 -7
@@ -16,10 +16,3 @@ Contents: hamradio/index wifi/index wwan/index - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/networking/device_drivers/wifi/index.rst +0 -7
@@ -10,10 +10,3 @@ Contents: intel/ipw2100 intel/ipw2200 - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/networking/device_drivers/wwan/index.rst +0 -7
@@ -10,10 +10,3 @@ Contents: iosm t7xx - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/networking/diagnostic/index.rst +0 -7
@@ -8,10 +8,3 @@ Networking Diagnostics :maxdepth: 2 twisted_pair_layer1_diagnostics.rst - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/process/debugging/index.rst +0 -9
@@ -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 ========================
Documentation/tools/rtla/index.rst +0 -7
@@ -18,10 +18,3 @@ behavior on specific hardware. rtla-timerlat-hist rtla-timerlat-top rtla-hwnoise - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/tools/rv/index.rst +0 -7
@@ -16,10 +16,3 @@ Runtime verification (rv) tool rv-mon-wip rv-mon-wwnr rv-mon-sched - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/zh_CN/arch/loongarch/index.rst +0 -7
@@ -18,10 +18,3 @@ LoongArch体系结构 irq-chip-model features - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/zh_CN/arch/mips/index.rst +0 -7
@@ -20,10 +20,3 @@ MIPS特性文档 ingenic-tcu features - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/zh_CN/arch/openrisc/index.rst +0 -8
@@ -22,11 +22,3 @@ OpenRISC 体系架构 Todolist: features - - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/zh_CN/arch/parisc/index.rst +0 -7
@@ -22,10 +22,3 @@ PA-RISC体系架构 Todolist: features - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/zh_CN/arch/riscv/index.rst +0 -8
@@ -21,11 +21,3 @@ RISC-V 体系结构 boot-image-header vm-layout patch-acceptance - - -.. only:: subproject and html - - 目录 - ==== - - * :ref:`genindex`
Documentation/translations/zh_CN/driver-api/phy/index.rst +0 -7
@@ -11,10 +11,3 @@ PHY 通用框架 Todolist: * samsung-usb2 - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/zh_TW/arch/loongarch/index.rst +0 -8
@@ -18,11 +18,3 @@ LoongArch體系結構 irq-chip-model features - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` -
Documentation/translations/zh_TW/arch/mips/index.rst +0 -8
@@ -20,11 +20,3 @@ MIPS特性文檔 ingenic-tcu features - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` -
Documentation/translations/zh_TW/arch/openrisc/index.rst +0 -9
@@ -22,12 +22,3 @@ OpenRISC 體系架構 Todolist: features - - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` -
Documentation/translations/zh_TW/arch/parisc/index.rst +0 -8
@@ -22,11 +22,3 @@ PA-RISC體系架構 Todolist: features - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` -
Documentation/userspace-api/gpio/index.rst +0 -7
@@ -9,10 +9,3 @@ GPIO Character Device Userspace API <chardev> Obsolete Userspace APIs <obsolete> - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/wmi/devices/index.rst +0 -7
@@ -13,10 +13,3 @@ the Linux kernel, their protocols and driver details. :glob: * - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Signature · 1 line
2.47.3
Re: [PATCH 1/4] Documentation: remove subproject index links deep in the structure
Quoted 14 lines · Jani Nikula
The idea of having
.. only:: subproject and html
Indices
=======* :ref:
genindexin
index.rstpages 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.
Quoted 4 lines
Cc Randy Dunlap <[email protected]>Cc Mauro Carvalho Chehab <[email protected]>Cc Jonathan Corbet <[email protected]>Signed-off-by Jani Nikula <[email protected]>
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
PATCH 2/4 Documentation: streamline subproject index link in translations
In reply to Jani NikulaRemove 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 <[email protected]>
Cc Mauro Carvalho Chehab <[email protected]>
Cc Jonathan Corbet <[email protected]>
Signed-off-by Jani Nikula <[email protected]>
--- 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(-)
Documentation/translations/index.rst +7 -0
@@ -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`
Documentation/translations/it_IT/RCU/index.rst +0 -7
@@ -10,10 +10,3 @@ Concetti su RCU :maxdepth: 3 torture - -.. only:: subproject and html - - Indici - ====== - - * :ref:`genindex`
Documentation/translations/it_IT/core-api/index.rst +0 -7
@@ -21,10 +21,3 @@ sul tema. :maxdepth: 1 ../RCU/index - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/it_IT/doc-guide/index.rst +0 -7
@@ -15,10 +15,3 @@ Come scrivere la documentazione del kernel sphinx kernel-doc parse-headers - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/it_IT/i2c/index.rst +0 -7
@@ -37,10 +37,3 @@ Argomenti avanzati .. toctree:: :maxdepth: 1 - -.. only:: subproject and html - - Indici - ====== - - * :ref:`genindex`
Documentation/translations/it_IT/index.rst +7 -0
@@ -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`
Documentation/translations/it_IT/locking/index.rst +0 -7
@@ -11,10 +11,3 @@ Sincronizzazione lockdep-design lockstat locktorture - -.. only:: subproject and html - - Indici - ====== - - * :ref:`genindex`
Documentation/translations/it_IT/process/index.rst +0 -7
@@ -98,10 +98,3 @@ degli sviluppatori: :maxdepth: 1 kernel-docs - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/zh_CN/admin-guide/index.rst +0 -7
@@ -123,10 +123,3 @@ Todolist: * vga-softcursor * video-output * xfs - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/zh_CN/core-api/index.rst +0 -7
@@ -139,10 +139,3 @@ Todolist: Todolist: librs - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/zh_CN/doc-guide/index.rst +0 -7
@@ -19,10 +19,3 @@ contributing maintainer-profile checktransupdate - -.. only:: subproject and html - - 目录 - ==== - - * :ref:`genindex`
Documentation/translations/zh_CN/driver-api/index.rst +0 -7
@@ -120,10 +120,3 @@ Todolist: * xillybus * zorro * hte/index - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/zh_CN/infiniband/index.rst +0 -9
@@ -29,12 +29,3 @@ infiniband tag_matching user_mad user_verbs - - - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/zh_CN/kbuild/index.rst +0 -8
@@ -26,11 +26,3 @@ TODO: - makefiles - modules - issues - - -.. only:: subproject and html - - 目录 - ===== - - * :ref:`genindex`
Documentation/translations/zh_CN/locking/index.rst +0 -7
@@ -34,10 +34,3 @@ TODOList: * percpu-rw-semaphore * robust-futexes * robust-futex-ABI - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/zh_CN/networking/index.rst +0 -7
@@ -151,10 +151,3 @@ Todolist: * xfrm_sysctl * xdp-rx-metadata * xsk-tx-metadata - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/zh_CN/peci/index.rst +0 -7
@@ -17,10 +17,3 @@ Linux PECI 子系统 peci - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/zh_CN/power/index.rst +0 -7
@@ -47,10 +47,3 @@ TODOList: * regulator/machine * regulator/overview * regulator/regulator - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/zh_CN/process/index.rst +0 -7
@@ -93,10 +93,3 @@ TODOLIST: * adding-syscalls * botching-up-ioctls * clang-format - -.. only:: subproject and html - - 目录 - ==== - - * :ref:`genindex`
Documentation/translations/zh_CN/rust/index.rst +0 -7
@@ -19,10 +19,3 @@ Rust general-information coding-guidelines arch-support - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/zh_CN/scheduler/index.rst +0 -7
@@ -36,10 +36,3 @@ TODOList: sched-rt-group text_files - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/zh_CN/sound/index.rst +0 -7
@@ -13,10 +13,3 @@ Linux 声音子系统文档 :maxdepth: 2 hd-audio/index - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/zh_CN/userspace-api/index.rst +0 -7
@@ -38,10 +38,3 @@ TODOList: * media/index * netlink/index * vduse - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/zh_CN/virt/index.rst +0 -7
@@ -29,10 +29,3 @@ TODOLIST: kvm/index uml/user_mode_linux_howto_v2 - -.. only:: html and subproject - - Indices - ======= - - * :ref:`genindex`
Documentation/translations/zh_TW/admin-guide/index.rst +0 -8
@@ -126,11 +126,3 @@ Todolist: * vga-softcursor * video-output * xfs - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` -
Documentation/translations/zh_TW/process/index.rst +0 -8
@@ -57,11 +57,3 @@ magic-number volatile-considered-harmful - -.. only:: subproject and html - - 目錄 - ==== - - * :ref:`genindex` -
Signature · 1 line
2.47.3
PATCH 3/4 Documentation: include the boilerplate for SPHINXDIRS index link
In reply to Jani NikulaRepeating 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 <[email protected]>
Cc Mauro Carvalho Chehab <[email protected]>
Cc Jonathan Corbet <[email protected]>
Signed-off-by Jani Nikula <[email protected]>
--- 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
Documentation/RCU/index.rst +1 -4
@@ -31,7 +31,4 @@ RCU Handbook .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/accel/index.rst +1 -4
@@ -14,7 +14,4 @@ Compute Accelerators .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/admin-guide/index.rst +1 -4
@@ -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
Documentation/bpf/index.rst +1 -4
@@ -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/
Documentation/cdrom/index.rst +1 -4
@@ -11,7 +11,4 @@ CD-ROM .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/conf.py +1 -1
@@ -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 = []
Documentation/core-api/index.rst +1 -4
@@ -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
Documentation/dev-tools/index.rst +1 -4
@@ -42,7 +42,4 @@ Documentation/process/debugging/index.rst .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/doc-guide/index.rst +1 -4
@@ -16,7 +16,4 @@ How to write kernel documentation .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/driver-api/index.rst +1 -4
@@ -150,7 +150,4 @@ Subsystem-specific APIs .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/fault-injection/index.rst +1 -4
@@ -14,7 +14,4 @@ Fault-injection .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/fb/index.rst +1 -4
@@ -53,7 +53,4 @@ Driver documentation .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/fpga/index.rst +1 -4
@@ -11,7 +11,4 @@ FPGA .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/gpu/drivers.rst +1 -4
@@ -29,7 +29,4 @@ GPU Driver Documentation .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: sphinx-includes/subproject-index.rst
Documentation/gpu/index.rst +1 -4
@@ -25,7 +25,4 @@ GPU Driver Developer's Guide .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/hwmon/index.rst +1 -4
@@ -279,7 +279,4 @@ Hardware Monitoring Kernel Drivers .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/i2c/index.rst +1 -4
@@ -69,7 +69,4 @@ Legacy documentation .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/infiniband/index.rst +1 -4
@@ -18,7 +18,4 @@ InfiniBand .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/input/index.rst +1 -4
@@ -13,7 +13,4 @@ Contents: .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/isdn/index.rst +1 -4
@@ -15,7 +15,4 @@ ISDN .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/kbuild/index.rst +1 -4
@@ -27,7 +27,4 @@ Kernel Build System .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/livepatch/index.rst +1 -4
@@ -18,7 +18,4 @@ Kernel Livepatching .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/locking/index.rst +1 -4
@@ -27,7 +27,4 @@ Locking .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/mhi/index.rst +1 -4
@@ -12,7 +12,4 @@ MHI .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/netlabel/index.rst +1 -4
@@ -15,7 +15,4 @@ NetLabel .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/networking/index.rst +1 -4
@@ -140,7 +140,4 @@ Contents: .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/pcmcia/index.rst +1 -4
@@ -14,7 +14,4 @@ PCMCIA .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/peci/index.rst +1 -4
@@ -10,7 +10,4 @@ PECI Subsystem .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/power/index.rst +1 -4
@@ -40,7 +40,4 @@ Power Management .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/process/index.rst +1 -4
@@ -111,7 +111,4 @@ developers: .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/rust/index.rst +1 -4
@@ -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
Documentation/scheduler/index.rst +1 -4
@@ -28,7 +28,4 @@ Scheduler .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/sound/index.rst +1 -4
@@ -18,7 +18,4 @@ Sound Subsystem Documentation .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/sphinx-includes/subproject-index.rst new file +4 -0
@@ -0,0 +1,4 @@ +Indices +======= + +* :ref:`genindex`
Documentation/spi/index.rst +1 -4
@@ -15,7 +15,4 @@ Serial Peripheral Interface (SPI) .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/target/index.rst +1 -4
@@ -13,7 +13,4 @@ TCM Virtual Device .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/tee/index.rst +1 -4
@@ -15,7 +15,4 @@ TEE Subsystem .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/timers/index.rst +1 -4
@@ -16,7 +16,4 @@ Timers .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/tools/index.rst +1 -4
@@ -15,7 +15,4 @@ more additions are needed here: .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/trace/index.rst +1 -4
@@ -98,7 +98,4 @@ tracing tool and framework. .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/translations/index.rst +1 -4
@@ -60,7 +60,4 @@ for help. .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/usb/index.rst +1 -4
@@ -34,7 +34,4 @@ USB support .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/userspace-api/index.rst +1 -4
@@ -70,7 +70,4 @@ Everything else .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/virt/index.rst +1 -4
@@ -19,7 +19,4 @@ Virtualization Support .. only:: html and subproject - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/w1/index.rst +1 -4
@@ -15,7 +15,4 @@ .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/watchdog/index.rst +1 -4
@@ -19,7 +19,4 @@ Watchdog Support .. only:: subproject and html - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Documentation/wmi/index.rst +1 -5
@@ -13,8 +13,4 @@ WMI Subsystem .. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` + .. include:: ../sphinx-includes/subproject-index.rst
Signature · 1 line
2.47.3
Re: [PATCH 3/4] Documentation: include the boilerplate for SPHINXDIRS index link
Quoted 20 lines · Jani Nikula
Repeating the index link boilerplate everywhere is tedious. Put it in a
subproject-index.rstsnippet 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 <[email protected]>Cc Mauro Carvalho Chehab <[email protected]>Cc Jonathan Corbet <[email protected]>Signed-off-by Jani Nikula <[email protected]>Documentation/conf.py +0
-0
Documentation/conf.py else: · line 41
Quoted 5 lines
Documentation/conf.py +1
-1@@ -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
Re: [PATCH 3/4] Documentation: include the boilerplate for SPHINXDIRS index link
Quoted 33 lines · Mauro Carvalho Chehab
Quoted 20 lines · Jani Nikula
Repeating the index link boilerplate everywhere is tedious. Put it in a
subproject-index.rstsnippet 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 <[email protected]>Cc Mauro Carvalho Chehab <[email protected]>Cc Jonathan Corbet <[email protected]>Signed-off-by Jani Nikula <[email protected]>Documentation/conf.py +0
-0Documentation/conf.py else: · line 41
Quoted 5 lines
Documentation/conf.py +1
-1@@ -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
Quoted 7 lines
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.
Signature · 1 line
Jani Nikula, Intel
Re: [PATCH 3/4] Documentation: include the boilerplate for SPHINXDIRS index link
Quoted 47 lines · Jani Nikula
Quoted 33 lines · Mauro Carvalho Chehab
Quoted 20 lines · Jani Nikula
Repeating the index link boilerplate everywhere is tedious. Put it in a
subproject-index.rstsnippet 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 <[email protected]>Cc Mauro Carvalho Chehab <[email protected]>Cc Jonathan Corbet <[email protected]>Signed-off-by Jani Nikula <[email protected]>Documentation/conf.py +0
-0Documentation/conf.py else: · line 41
Quoted 5 lines
Documentation/conf.py +1
-1@@ -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
Quoted 7 lines
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.
Quoted 4 lines
The whole
dyn_exclude_patternslooks like overkill to me. It should just look atexclude_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.
Signature · 2 lines
Thanks, Mauro
PATCH 4/4 Documentation: use a source-read extension to include the index boilerplate
In reply to Jani NikulaReduce 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 <[email protected]>
Cc Mauro Carvalho Chehab <[email protected]>
Cc Jonathan Corbet <[email protected]>
Signed-off-by Jani Nikula <[email protected]>
--- 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(-)
Documentation/RCU/index.rst +0 -4
@@ -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
Documentation/accel/index.rst +0 -4
@@ -11,7 +11,3 @@ Compute Accelerators amdxdna/index qaic/index rocket/index - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/admin-guide/index.rst +0 -4
@@ -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
Documentation/bpf/index.rst +0 -4
@@ -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/
Documentation/cdrom/index.rst +0 -4
@@ -8,7 +8,3 @@ CD-ROM :maxdepth: 1 cdrom-standard - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/conf.py +6 -0
@@ -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)
Documentation/core-api/index.rst +0 -4
@@ -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
Documentation/dev-tools/index.rst +0 -5
@@ -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
Documentation/doc-guide/index.rst +0 -4
@@ -13,7 +13,3 @@ How to write kernel documentation contributing maintainer-profile checktransupdate - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/driver-api/index.rst +0 -4
@@ -147,7 +147,3 @@ Subsystem-specific APIs wmi xilinx/index zorro - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/fault-injection/index.rst +0 -4
@@ -11,7 +11,3 @@ Fault-injection notifier-error-inject nvme-fault-injection provoke-crashes - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/fb/index.rst +0 -4
@@ -50,7 +50,3 @@ Driver documentation vesafb viafb vt8623fb - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/fpga/index.rst +0 -4
@@ -8,7 +8,3 @@ FPGA :maxdepth: 1 dfl - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/gpu/drivers.rst +0 -4
@@ -26,7 +26,3 @@ GPU Driver Documentation panthor zynqmp nova/index - -.. only:: subproject and html - - .. include:: sphinx-includes/subproject-index.rst
Documentation/gpu/index.rst +0 -4
@@ -22,7 +22,3 @@ GPU Driver Developer's Guide implementation_guidelines todo rfc/index - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/hwmon/index.rst +0 -4
@@ -276,7 +276,3 @@ Hardware Monitoring Kernel Drivers xdpe12284 xdpe152c4 zl6100 - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/i2c/index.rst +0 -4
@@ -66,7 +66,3 @@ Legacy documentation :maxdepth: 1 old-module-parameters - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/infiniband/index.rst +0 -4
@@ -15,7 +15,3 @@ InfiniBand ucaps user_mad user_verbs - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/input/index.rst +0 -4
@@ -10,7 +10,3 @@ Contents: input_uapi input_kapi devices/index - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/isdn/index.rst +0 -4
@@ -12,7 +12,3 @@ ISDN m_isdn credits - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/kbuild/index.rst +0 -4
@@ -24,7 +24,3 @@ Kernel Build System gendwarfksyms bash-completion - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/livepatch/index.rst +0 -4
@@ -15,7 +15,3 @@ Kernel Livepatching system-state reliable-stacktrace api - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/locking/index.rst +0 -4
@@ -24,7 +24,3 @@ Locking percpu-rw-semaphore robust-futexes robust-futex-ABI - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/mhi/index.rst +0 -4
@@ -9,7 +9,3 @@ MHI mhi topology - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/netlabel/index.rst +0 -4
@@ -12,7 +12,3 @@ NetLabel lsm_interface draft_ietf - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/networking/index.rst +0 -4
@@ -137,7 +137,3 @@ Contents: xfrm_sysctl xdp-rx-metadata xsk-tx-metadata - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/pcmcia/index.rst +0 -4
@@ -11,7 +11,3 @@ PCMCIA devicetable locking driver-changes - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/peci/index.rst +0 -4
@@ -7,7 +7,3 @@ PECI Subsystem .. toctree:: peci - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/power/index.rst +0 -4
@@ -37,7 +37,3 @@ Power Management regulator/machine regulator/overview regulator/regulator - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/process/index.rst +0 -4
@@ -108,7 +108,3 @@ developers: kernel-docs deprecated - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/rust/index.rst +0 -4
@@ -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
Documentation/scheduler/index.rst +0 -4
@@ -25,7 +25,3 @@ Scheduler sched-debug text_files - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/sound/index.rst +0 -4
@@ -15,7 +15,3 @@ Sound Subsystem Documentation cards/index codecs/index utimers - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/spi/index.rst +0 -4
@@ -12,7 +12,3 @@ Serial Peripheral Interface (SPI) butterfly spi-lm70llp spi-sc18is602 - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/target/index.rst +0 -4
@@ -10,7 +10,3 @@ TCM Virtual Device tcmu-design tcm_mod_builder scripts - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/tee/index.rst +0 -4
@@ -12,7 +12,3 @@ TEE Subsystem amd-tee ts-tee qtee - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/timers/index.rst +0 -4
@@ -13,7 +13,3 @@ Timers no_hz timekeeping delay_sleep_functions - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/tools/index.rst +0 -4
@@ -12,7 +12,3 @@ more additions are needed here: rtla/index rv/index - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/trace/index.rst +0 -4
@@ -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
Documentation/translations/index.rst +0 -4
@@ -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
Documentation/usb/index.rst +0 -4
@@ -31,7 +31,3 @@ USB support usb-help text_files - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/userspace-api/index.rst +0 -4
@@ -67,7 +67,3 @@ Everything else futex2 perf_ring_buffer ntsync - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/virt/index.rst +0 -4
@@ -16,7 +16,3 @@ Virtualization Support coco/sev-guest coco/tdx-guest hyperv/index - -.. only:: html and subproject - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/w1/index.rst +0 -4
@@ -12,7 +12,3 @@ w1-netlink.rst masters/index slaves/index - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/watchdog/index.rst +0 -4
@@ -16,7 +16,3 @@ Watchdog Support watchdog-pm wdt convert_drivers_to_kernel_api - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Documentation/wmi/index.rst +0 -4
@@ -10,7 +10,3 @@ WMI Subsystem acpi-interface driver-development-guide devices/index - -.. only:: subproject and html - - .. include:: ../sphinx-includes/subproject-index.rst
Signature · 1 line
2.47.3
Re: [PATCH 4/4] Documentation: use a source-read extension to include the index boilerplate
Quoted 17 lines · Jani Nikula
Reduce boilerplate all over the place by adding a small ad hoc extension in
conf.pythat adds the../sphinx-includes/subproject-index.rstinclude to all SPHINXDIRS builds.Note that the docname is just 'index', because the SPHINXDIRS builds happen in the subdirectories.
Cc Randy Dunlap <[email protected]>Cc Mauro Carvalho Chehab <[email protected]>Cc Jonathan Corbet <[email protected]>Signed-off-by Jani Nikula <[email protected]>Documentation/conf.py +0
-0
Documentation/conf.py kerneldoc_srctree = ".." · line 596
Quoted 8 lines
Documentation/conf.py +5
-0@@ -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
Re: [PATCH 4/4] Documentation: use a source-read extension to include the index boilerplate
Quoted 30 lines · Mauro Carvalho Chehab
Quoted 17 lines · Jani Nikula
Reduce boilerplate all over the place by adding a small ad hoc extension in
conf.pythat adds the../sphinx-includes/subproject-index.rstinclude to all SPHINXDIRS builds.Note that the docname is just 'index', because the SPHINXDIRS builds happen in the subdirectories.
Cc Randy Dunlap <[email protected]>Cc Mauro Carvalho Chehab <[email protected]>Cc Jonathan Corbet <[email protected]>Signed-off-by Jani Nikula <[email protected]>Documentation/conf.py +0
-0Documentation/conf.py kerneldoc_srctree = ".." · line 596
Quoted 8 lines
Documentation/conf.py +5
-0@@ -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:
Quoted 1 line
$ 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.
Quoted 10 lines
Traceback =========
File "
/usr/lib/python3.14/site-packages/sphinx/util/parallel.py", line 137, in_join_one
raiseSphinxParallelError(*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
Signature · 1 line
Jani Nikula, Intel
Re: [PATCH 4/4] Documentation: use a source-read extension to include the index boilerplate
Quoted 31 lines · Jani Nikula
Quoted 30 lines · Mauro Carvalho Chehab
Quoted 17 lines · Jani Nikula
Reduce boilerplate all over the place by adding a small ad hoc extension in
conf.pythat adds the../sphinx-includes/subproject-index.rstinclude to all SPHINXDIRS builds.Note that the docname is just 'index', because the SPHINXDIRS builds happen in the subdirectories.
Cc Randy Dunlap <[email protected]>Cc Mauro Carvalho Chehab <[email protected]>Cc Jonathan Corbet <[email protected]>Signed-off-by Jani Nikula <[email protected]>Documentation/conf.py +0
-0Documentation/conf.py kerneldoc_srctree = ".." · line 596
Quoted 8 lines
Documentation/conf.py +5
-0@@ -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:
Quoted 7 lines
Quoted 1 line
$ make SPHINXDIRS=userspace-api/media htmldocsUgh, 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
Randy Dunlap
reviewerRe: [PATCH 4/4] Documentation: use a source-read extension to include the index boilerplate
In reply to Jani NikulaQuoted 31 lines · Jani Nikula
Quoted 30 lines · Mauro Carvalho Chehab
Quoted 17 lines · Jani Nikula
Reduce boilerplate all over the place by adding a small ad hoc extension in
conf.pythat adds the../sphinx-includes/subproject-index.rstinclude to all SPHINXDIRS builds.Note that the docname is just 'index', because the SPHINXDIRS builds happen in the subdirectories.
Cc Randy Dunlap <[email protected]>Cc Mauro Carvalho Chehab <[email protected]>Cc Jonathan Corbet <[email protected]>Signed-off-by Jani Nikula <[email protected]>Documentation/conf.py +0
-0Documentation/conf.py kerneldoc_srctree = ".." · line 596
Quoted 8 lines
Documentation/conf.py +5
-0@@ -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:
Quoted 7 lines
Quoted 1 line
$ make SPHINXDIRS=userspace-api/media htmldocsUgh, 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.
Signature · 1 line
~Randy
Randy Dunlap
reviewerQuoted 10 lines · 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
Quoted 3 lines
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.
Signature · 1 line
~Randy
Jonathan Corbet
maintainerQuoted 8 lines · 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
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
Quoted 11 lines · Jonathan Corbet
Quoted 8 lines · 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
Quoted 2 lines
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.
Signature · 1 line
Jani Nikula, Intel
Quoted 25 lines · Jani Nikula
Quoted 11 lines · Jonathan Corbet
Quoted 8 lines · 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
boilerplateQuoted 2 lines
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.
Quoted 6 lines
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.
Signature · 1 line
Jani Nikula, Intel