From b9bc3020f7c695746fb7923b155038f358f29df0 Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Jan 08 2026 17:52:54 +0000 Subject: [PATCH 1/4] Repo tooling: Adopt the docsbuilder.sh script Instead of using podman commands directly in the Makefile, add the `docsbuilder.sh` script from the [docs templates repo][1]. Rewrite the Makefile to use docsbuilder commands to perform its functions. Changes: - The preview URL changes from `https://localhost:8000` to `https://localhost:8080/` - `build` is now a synonym for `doc` - `serve` now runs `docsbuilder -p` which automatically rebuilds the doc first - `watch` is now available to start a server that automatically rebuilds the preview on file changes - `linkcheck` will automatically start a preview server before running `linkchecker` [1]: https://gitlab.com/fedora/docs/templates/fedora-docs-template --- diff --git a/Makefile b/Makefile index a0ada9e..ac6f930 100644 --- a/Makefile +++ b/Makefile @@ -1,19 +1,25 @@ mkfile_path := $(abspath $(lastword $(MAKEFILE_LIST))) mkfile_dir := $(patsubst %/,%,$(dir $(mkfile_path))) +docsbuilder := $(abspath $(mkfile_dir)/docsbuilder.sh) doc: - podman run --rm -it -v "$(mkfile_dir):/antora:z" \ - antora/antora --html-url-extension-style=indexify site.yml + $(docsbuilder) -b + +build: doc .ONESHELL: -serve: - @cd "$(mkfile_dir)/public" +serve: $(info *** Make sure to refresh pages without cache ***) - python3 -m http.server + $(docsbuilder) -p + +watch: + $(docsbuilder) -a linkcheck: - linkchecker http://localhost:8000 --complete --check-extern --no-robots \ + $(docsbuilder) -k + $(docsbuilder) -p + linkchecker http://localhost:8080 --complete --check-extern --no-robots \ --ignore-url "drupal.org" .DEFAULT_GOAL := doc -.PHONY: doc linkcheck serve +.PHONY: doc linkcheck serve watch diff --git a/docsbuilder.sh b/docsbuilder.sh new file mode 100755 index 0000000..fcb54d6 --- /dev/null +++ b/docsbuilder.sh @@ -0,0 +1,292 @@ +#!/bin/bash +# script to watch source directory for changes, and re-run build and preview +# +# License: MIT +# https://fedoraproject.org/wiki/Licensing:MIT#Another_Minimal_variant_(found_in_libatomic_ops) +# +# Copyright (c) Fedora community contributors. +# +# THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED OR +# IMPLIED. ANY USE IS AT YOUR OWN RISK. +# +# Permission is hereby granted to use or copy this program for any purpose, +# provided the above notices are retained on all copies. Permission to modify +# the code and to distribute modified code is granted, provided the above +# notices are retained, and a notice that the code was modified is included +# with the above copyright notice. + + +script_name="docsbuilder.sh" +script_source="https://gitlab.com/fedora/docs/templates/fedora-docs-template/-/raw/main/${script_name}" +version="1.2.0" +image="docker.io/antora/antora" +cmd="--html-url-extension-style=indexify site.yml" +srcdir="guidelines" +buildir="public" +previewpidfile="preview.pid" + +# 4913: for vim users, vim creates a temporary file to test it can write to +# directory +# https://groups.google.com/g/vim_dev/c/sppdpElxY44 +# .git: so we don't get rebuilds each time git metadata changes +inotifyignore="\.git.*|4913" + +watch_and_build () { + if ! command -v inotifywait > /dev/null + then + echo "inotifywait command could not be found. Please install inotify-tools." + echo "On Fedora, run: sudo dnf install inotify-tools" + stop_preview_and_exit + else + # check for git + # required to get ignorelist + if ! command -v git > /dev/null + then + echo "git command could not be found. Please install git." + echo "On Fedora, run: sudo dnf install git-core" + stop_preview_and_exit + else + # Get files not being tracked, we don't watch for changes in these. + # Could hard code, but people use different editors that may create + # temporary files that are updated regularly and so on, so better + # to get the list from git. It'll also look at global gitingore + # settings and so on. + inotifyignore="$(git status -s --ignored | grep '^!!' | sed -e 's/^!! //' | tr '\n' '|')${inotifyignore}" + fi + + while true + do + echo "Watching current directory (excluding: ${inotifyignore}) for changes and re-building as required. Use Ctrl C to stop." + inotifywait -q --exclude "($inotifyignore)" -e modify,create,delete,move -r . && echo "Change detected, rebuilding.." && build + done + fi +} + +build () { + if [ "$(uname)" == "Darwin" ]; then + # Running on macOS. + # Let's assume that the user has the Docker CE installed + # which doesn't require a root password. + echo "" + echo "This build script is using Docker container runtime to run the build in an isolated environment." + echo "" + docker run --rm -it -v $(pwd):/antora $image $cmd + + elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then + # Running on Linux. + # Check whether podman is available, else faill back to docker + # which requires root. + + if [ -n "$(command -v podman)" ]; then + echo "" + echo "This build script is using Podman to run the build in an isolated environment." + echo "" + podman run --rm -it -v $(pwd):/antora:z $image $cmd --stacktrace + + elif [ -n "$(command -v docker)" ]; then + echo "" + echo "This build script is using Docker to run the build in an isolated environment." + echo "" + + if groups | grep -wq "docker"; then + docker run --rm -it -v $(pwd):/antora:z $image $cmd + else + echo "" + echo "This build script is using $runtime to run the build in an isolated environment. You might be asked for your password." + echo "You can avoid this by adding your user to the 'docker' group, but be aware of the security implications. See https://docs.docker.com/install/linux/linux-postinstall/." + echo "" + sudo docker run --rm -it -v $(pwd):/antora:z $image $cmd + fi + + else + echo "" + echo "Error: Container runtime haven't been found on your system. Fix it by:" + echo "$ sudo dnf install podman" + exit 1 + fi + fi +} + +start_preview () { + + # clean up a preview that may be running + stop_preview + + # always run an initial build so preview shows latest version + build + + if [ "$(uname)" == "Darwin" ]; then + # Running on macOS. + # Let's assume that the user has the Docker CE installed + # which doesn't require a root password. + echo "The preview will be available at http://localhost:8080/" + docker run --rm -v $(pwd):/antora:ro -v $(pwd)/nginx.conf:/etc/nginx/conf.d/default.conf:ro -p 8080:80 nginx + + elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then + # Running on Linux. + # Fedora Workstation has python3 installed as a default, so using that + echo "" + echo "The preview is available at http://localhost:8080" + echo "" + pushd "${buildir}" > /dev/null 2>&1 + python3 -m http.server 8080 & + echo "$!" > ../"${previewpidfile}" + popd > /dev/null 2>&1 + fi +} + +stop_preview () { + if [ -e "${previewpidfile}" ] + then + PID=$(cat "${previewpidfile}") + kill $PID + echo "Stopping preview server (running with PID ${PID}).." + rm -f "${previewpidfile}" + else + echo "No running preview server found to stop: no ${previewpidfile} file found." + fi +} + +stop_preview_and_exit () +{ + # stop and also exit the script + + # if stop_preview is trapped, then SIGINT doesn't stop the build loop. So + # we need to make sure we also exit the script. + + # stop_preview is called before other functions, so we cannot add exit to + # it. + stop_preview + exit 0 +} + + +# https://apple.stackexchange.com/questions/83939/compare-multi-digit-version-numbers-in-bash/123408#123408 +version () { echo "$@" | awk -F. '{ printf("%d%03d%03d%03d\n", $1,$2,$3,$4); }'; } + + +check_update () { + if ! command -v curl > /dev/null + then + echo "curl command could not be found. Please install curl." + echo "On Fedora, run: sudo dnf install curl" + exit 0 + fi + script_version="$(grep "^version=" ${script_name} | cut -d '=' -f2 | tr --delete '"')" + tempdir="$(mktemp -d)" + echo "$tempdir" + pushd "$tempdir" > /dev/null 2>&1 + curl "$script_source" --silent --output "${script_name}" + upstream_version="$(grep "^version=" ${script_name} | cut -d '=' -f2 | tr --delete '"')" + echo "${upstream_version}" + if [ $(version $upstream_version) -gt $(version $script_version) ]; then + echo "Update available" + echo "Script version $upstream_version is available at $script_source" + echo "This version is $script_version." + echo "Please use the '-U' option to update." + echo + fi + popd > /dev/null 2&>1 +} + +install_update () { + if ! command -v curl > /dev/null + then + echo "curl command could not be found. Please install curl." + echo "On Fedora, run: sudo dnf install curl" + exit 0 + fi + curl "$script_source" --silent --output "${script_name}.new" + mv "${script_name}.new" "${script_name}" + chmod +x "${script_name}" +} + +usage() { + echo "$0: Build and preview Fedora antora based documentation" + echo + echo "Usage: $0 [-awbpkh]" + echo + echo "-a: start preview, start watcher and rebuilder" + echo "-w: start watcher and rebuilder" + echo "-b: rebuild" + echo "-p: start_preview" + echo "-k: stop_preview" + echo "-h: print this usage text and exit" + echo "-u: check builder script update" + echo "-U: install builder script from upstream" + echo + echo "Maintained by the Fedora documentation team." + echo "Please contact on our channels: https://docs.fedoraproject.org/en-US/fedora-docs/#find-docs" +} + +# check if the script is being run in a Fedora docs repository +if [ ! -e "site.yml" ] +then + echo "site.yml not be found." + echo "This does not appear to be a Fedora Antora based documentation repository." + echo "Exiting." + echo + usage + exit 1 +fi + + +if [ $# -lt 1 ] +then + echo "No options provided, running preview with watch and build." + echo "Run script with '-h' to see all available options." + echo + echo + trap stop_preview_and_exit INT + start_preview + watch_and_build + stop_preview +fi + +# parse options +while getopts "awbpkhuU" OPTION +do + case $OPTION in + a) + # handle sig INT to stop the preview + trap stop_preview_and_exit INT + start_preview + watch_and_build + stop_preview + exit 0 + ;; + w) + watch_and_build + exit 0 + ;; + b) + build + exit 0 + ;; + p) + start_preview + echo "Please run ./${script_name} -k to stop the preview server" + exit 0 + ;; + k) + stop_preview + exit 0 + ;; + h) + usage + exit 0 + ;; + u) + check_update + exit 0 + ;; + U) + install_update + exit 0 + ;; + ?) + usage + exit 1 + ;; + esac +done From f059e0d1bce6b8a0f5f8f99f74c2fdaba1c5a24f Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Jan 08 2026 17:52:54 +0000 Subject: [PATCH 2/4] linkchecker doesn't support --complete argument --- diff --git a/Makefile b/Makefile index ac6f930..e395318 100644 --- a/Makefile +++ b/Makefile @@ -18,7 +18,7 @@ watch: linkcheck: $(docsbuilder) -k $(docsbuilder) -p - linkchecker http://localhost:8080 --complete --check-extern --no-robots \ + linkchecker http://localhost:8080 --check-extern --no-robots \ --ignore-url "drupal.org" .DEFAULT_GOAL := doc From ee8f61f2e514efbeaf4a3db44681858238d6de19 Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Jan 08 2026 17:52:54 +0000 Subject: [PATCH 3/4] Shut down server after running linkchecker --- diff --git a/Makefile b/Makefile index e395318..370fffa 100644 --- a/Makefile +++ b/Makefile @@ -20,6 +20,7 @@ linkcheck: $(docsbuilder) -p linkchecker http://localhost:8080 --check-extern --no-robots \ --ignore-url "drupal.org" + $(docsbuilder) -k .DEFAULT_GOAL := doc .PHONY: doc linkcheck serve watch From 43294c77c61c6f2a64d0a0b404275943f6151f11 Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Jan 08 2026 17:52:54 +0000 Subject: [PATCH 4/4] linkchecker: Add ignores for housekeeping links The Antora server will include a language-switching link and an edit link for each file, both of which aren't valid in the preview and need to be ignored. The edit link takes the form `file:///antora/...`, a path that's only valid inside the container. The language link points from every document `https://localhost:8080/guidelines/foo` to a language-specific URL like `https://localhost:8080/en-US/guidelines/foo` The latter may need to be tweaked if they're dependent on the system locale of the user running linkchecker. Ignoring `https://localhost:8080/en-US` works for me, but may not be universal. --- diff --git a/Makefile b/Makefile index 370fffa..52c9fae 100644 --- a/Makefile +++ b/Makefile @@ -19,7 +19,9 @@ linkcheck: $(docsbuilder) -k $(docsbuilder) -p linkchecker http://localhost:8080 --check-extern --no-robots \ - --ignore-url "drupal.org" + --ignore-url "drupal.org" \ + --ignore-url "file:///antora" \ + --ignore-url 'http://localhost:8080/en-US' $(docsbuilder) -k .DEFAULT_GOAL := doc