From 2cc547eac76f4407709c03b1a0ffe5aad6bc27bf Mon Sep 17 00:00:00 2001 From: Thomas Richard Date: Thu, 6 Aug 2026 19:41:43 +0200 Subject: [PATCH] kernel_patch_verify: add test to build kernel Documentation Add a test to automatically build kernel Documentation in html format if a patch modifies a file in Documentation/. Option -H shall be used to enable it. Signed-off-by: Thomas Richard --- build-env.sh | 2 ++ kernel_patch_verify | 55 ++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 54 insertions(+), 3 deletions(-) diff --git a/build-env.sh b/build-env.sh index b986419..0c97e0b 100755 --- a/build-env.sh +++ b/build-env.sh @@ -62,6 +62,8 @@ download_build_install_python_deps() python -m pip install git+https://github.com/devicetree-org/dt-schema.git@$DTSCHEMA_REV # Install patchwise and it's dependencies python -m pip install git+https://github.com/nmenon/PatchWise.git@kernel_patch_verify_patchwise + # Install dependencies to build kernel Documentation + python -m pip install -r https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/sphinx/requirements.txt # HACK - Just dont stick around with 20.0.0 clang.. use the bleeding edge.. #find /usr/local/venv/lib/python3*/site-packages/patchwise -iname *.py|xargs sed -ie "s/20.0.0/23.0.0/g" rm -rf "/tmp/.cache/" /tmp/get-pip.py diff --git a/kernel_patch_verify b/kernel_patch_verify index 2728388..0bdf00d 100755 --- a/kernel_patch_verify +++ b/kernel_patch_verify @@ -390,6 +390,25 @@ btest_refcheckdocs() { kmake_single refcheckdocs 1>&2 } +doctest_htmldocs() { + local test_paths=() + # No files in Documentation/, so no need to build the doc + if [ "$@" = "" ]; then + return + fi + # Extract directories to only build needed Documentation directories and + # not the entire documentation. If a root file is modified we have to + # build the whole documentation. + # Documentation/hid/index.rst => hid + # Documentation/devicetree/bindings/index.rst => devicetree/bindings + # Documentation/index.rst => . + for i in "$@" + do + test_paths="$(echo $i | sed 's|^Documentation/\(.*\)/.*$|\1|; t; s|^Documentation/.*$|.|')" + done + kmake SPHINXOPTS='-vv' SPHINXDIRS="${test_paths[@]}" cleandocs htmldocs >/dev/null +} + btest_kbuild() { if [ "$UBOOT_TESTING" -eq 0 ]; then kmake C=1 $KP_TARGETS "$MODULES" > /dev/null @@ -645,6 +664,7 @@ test_patch() { readarray -t ofiles <<< "$(diffstat -lp1 "$patch"|grep -P '\.[Sc]$'|sort|sed -e "s/[Sc]$/o/g")" readarray -t yfiles <<< "$(diffstat -lp1 "$patch"|grep -P '\.yaml$'|sort)" readarray -t dfiles <<< "$(diffstat -lp1 "$patch"|grep 'boot/dts'|grep -v 'Makefile'|sort)" + readarray -t docfiles <<< "$(diffstat -lp1 "$patch"|grep '^Documentation'|sort)" # Run sequential tests TESTS_P_SET="ptest_am ptest_check" @@ -672,12 +692,17 @@ test_patch() { TESTS_D_SET="$TESTS_D_SET dtest_dtbs_check" DWARNING="(dtbs_check is enabled, HIGHLY RECOMMEND custom .config to save time)" fi + # Run Documentation tests + if [ -n "$DOC_TESTS" ]; then + TESTS_DOC_SET="doctest_htmldocs" + fi echo "Tests to run on C files(parallel): $TESTS_C_SET" echo "Tests to run on yaml files: $TESTS_Y_SET" echo "Tests to run on dtb files$DWARNING: $TESTS_D_SET" echo "Tests to run on Patch: $TESTS_P_SET" echo "Tests to run on Build: $TESTS_B_SET" + echo "Tests to run on Documentation: $TESTS_DOC_SET" run_test start "$TEST_DIR" defconfig # run twice - we just want end build errors.. @@ -714,6 +739,11 @@ test_patch() { done PIDS="" + for test_s in $TESTS_DOC_SET + do + run_test start "$TEST_DIR" "$test_s" "${docfiles[@]}" + done + for test_s in $TESTS_P_SET do run_test_dummy start "$TEST_DIR" "$test_s" "$patch" @@ -754,6 +784,11 @@ test_patch() { wait "$pid" done PIDS="" + + for test_s in $TESTS_DOC_SET + do + run_test end "$TEST_DIR" "$test_s" "${docfiles[@]}" + done } report_patch() { @@ -761,7 +796,7 @@ report_patch() { log_marker "::test results START " "$(basename "$1")" "::" log_me "Subject: $Subject" echo -en "\n" "$(basename "$1")" "Tests: " >> "$LOG_SUMMARY_FILE" - report_tests defconfig btest_kbuild "$TESTS_C_SET" "$TESTS_B_SET" "$TESTS_P_SET" "$TESTS_Y_SET" "$TESTS_D_SET" + report_tests defconfig btest_kbuild "$TESTS_C_SET" "$TESTS_B_SET" "$TESTS_P_SET" "$TESTS_Y_SET" "$TESTS_D_SET" "$TESTS_DOC_SET" log_marker "::test results END" "$(basename "$1")" "::" } @@ -969,6 +1004,13 @@ check_missing_application() { fi done + # Documentation has its own script to find missing dependencies + # depending the distro, so use it. + if [ -n "$DOC_TESTS" ]; then + tools/docs/sphinx-pre-install --no-pdf >/dev/null 2>&1 || \ + APPS_MISSING="$APPS_MISSING sphinx-pre-install" + fi + # Check for optional tools (Claude, review_one.sh, semcode) # Check if claude command is available @@ -1011,6 +1053,7 @@ recommend_missing_application() { done fi echo "" >&2 + echo "sphinx-pre-install means some dependencies are missing to build the kernel doc, run 'tools/docs/sphinx-pre-install --pdf' for more details" >&2 echo "Please install the missing applications and try again." >&2 return 2 fi @@ -1054,7 +1097,8 @@ usage() { "-Z : Dont filter dtb warnings ($DTB_FILTER_LIST)" \ "-m : maximum line length number to be passed on to checkpatch.pl" \ "-S smatch_script : Provide a custom smatch_script instead of creating our own" \ - "-s : Test current b4 branch, it automatically sets test_branch and base_branch" + "-s : Test current b4 branch, it automatically sets test_branch and base_branch" \ + "-H : Build kernel documentation (make htmldocs)" printf '%s\n' \ '' \ @@ -1101,7 +1145,7 @@ ORIDE=0 DTB_NOSKIP=0 BUILD_OUTPUT_DIR="" PATCHWISE=0 -while getopts "S:n:j:c:T:B:l:p:b:t:m:M:O:123456789ACdDUVZLPs" opt; do +while getopts "S:n:j:c:T:B:l:p:b:t:m:M:O:123456789ACdDUVZLPsH" opt; do case $opt in j) KM_CPUS=$OPTARG @@ -1282,6 +1326,11 @@ while getopts "S:n:j:c:T:B:l:p:b:t:m:M:O:123456789ACdDUVZLPs" opt; do APPS_NEEDED="$APPS_NEEDED b4" B4="yes" ;; + H) + # check_missing_application will automatically run + # sphinx-pre-install script to get missing dependencies + DOC_TESTS=1 + ;; \?) usage "Invalid option: -$OPTARG" exit 1