btrfs-progs: ci: build manual page previews if source changed

Extend CI workflow of devel branch to generate manual page preview as it
would be rendered in a terminal. The output is in the workflow summary
page, for each file changed (if any).

Issue: #824
Signed-off-by: David Sterba <dsterba@suse.com>

.github/workflows/devel.yml

@@ -12,19 +12,31 @@ on:
       - 'CI/**'
 jobs:
   build-simple:
-    name: Simple build tests
+    name: Simple build tests, manual page build test
     strategy:
       matrix:
         compiler: [ gcc, clang ]
     runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
+      - name: Get changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v44
       - run: sudo modprobe btrfs
       - run: sudo apt-get install -y pkg-config gcc liblzo2-dev libzstd-dev libblkid-dev uuid-dev zlib1g-dev libext2fs-dev e2fsprogs libudev-dev python3-sphinx sphinx-rtd-theme-common python3-sphinx-rtd-theme
       - name: Configure
-        run: ./autogen.sh && CC=${{ matrix.compiler}} ./configure
+        run: ./autogen.sh && CC=${{ matrix.compiler }} ./configure
       - name: Documentation
         run: make V=1 -C Documentation
+      - name: Generate manual pages preview
+        if: ${{ matrix.compiler == 'gcc' }}
+        env:
+          ALL_CHANGED_FILES: ${{ steps.changed-files.outputs.all_changed_files }}
+        run: |
+          for file in ${ALL_CHANGED_FILES}; do
+            echo "$file was changed, generate preview to summary"
+            Documentation/man-preview.sh "$file" >> $GITHUB_STEP_SUMMARY
+          done
       - name: Make static
         run: make V=1 EXTRA_CFLAGS='-march=x86-64' static
       - name: Make box.static

Documentation/man-preview.sh

@@ -0,0 +1,47 @@
+#!/bin/sh
+# Generate manual page preview as rendered to a terminal, without colors or
+# text attributes, encapsualted html, usable for CI summary
+
+if ! [ -f "$1" ]; then
+	exit 0
+fi
+
+width=120
+prefix=Documentation/
+here=$(pwd)
+
+if [ "$(basename \"$here\")" = 'Documentation' ]; then
+	prefix=
+fi
+
+fn="$1"
+bn=$(basename "$fn" .rst)
+
+if [ "$bn" = 'btrfs-man5' ]; then
+	# This is the only page that does not follow from the file name,
+	# the translation could be done using the man_pages table in conf.py
+	# but for one entry let's add a exception here
+	man="${prefix}_build/man/btrfs.5"
+else
+	man=$(find "${prefix}"_build/man -name "$bn".'[0-9]')
+fi
+
+if ! [ -f "$man" ]; then
+	#echo "ERROR: cannot find manual page '$man' from bn $bn fn $fn <br/>"
+	exit 0
+fi
+
+cat << EOF
+<details>
+<summary>$fn</summary>
+
+\`\`\`
+EOF
+
+COLUMNS="$width" man -P cat "$man"
+
+cat << EOF
+\`\`\`
+
+</details>
+EOF