From 83118db9ad7b08209c41a2484d9bdde2eeb65b3c Mon Sep 17 00:00:00 2001 From: Peter Boy Date: Thu, 10 Aug 2023 13:49:39 +0200 Subject: [PATCH] Updated authoring tools. --- build.sh | 55 +--------- docsbuilder.sh | 292 +++++++++++++++++++++++++++++++++++++++++++++++++ preview.sh | 21 +--- 3 files changed, 300 insertions(+), 68 deletions(-) create mode 100755 docsbuilder.sh diff --git a/build.sh b/build.sh index 96c2b69..8b3a8ca 100755 --- a/build.sh +++ b/build.sh @@ -1,52 +1,5 @@ -#!/bin/sh +#!/bin/bash -image="docker.io/antora/antora" -cmd="--html-url-extension-style=indexify site.yml" - -if uname | grep -iwq 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 uname | grep -iq linux; then - # Running on Linux. - # there isn't an antora/aarch64 container, antora can be installed locally - # Check whether podman is available, else faill back to docker - # which requires root. - - if [ -f /usr/local/bin/antora ]; then - /usr/local/bin/antora "${cmd}" - elif uname -m | grep -iwq aarch64; then - echo "no antora/aarch64 container try just \`npm install -g @antora/cli @antora/site-generator-default\`" - elif [ -f /usr/bin/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} - - elif [ -f /usr/bin/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 "You might be asked for your password." - echo "You can avoid this by adding your user to the 'docker' group," - echo "but be aware of the security implications." - echo "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 +echo "Deprecated. Use the docsbuilder.sh script instead" +sleep 2 +./docsbuilder.sh -b diff --git a/docsbuilder.sh b/docsbuilder.sh new file mode 100755 index 0000000..418b7e3 --- /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="modules" +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 diff --git a/preview.sh b/preview.sh index 4270107..09dc4cc 100755 --- a/preview.sh +++ b/preview.sh @@ -1,18 +1,5 @@ -#!/bin/sh +#!/bin/bash -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 "" - cd ./public - python3 -m http.server 8080 -fi +echo "Deprecated. Use the docsbuilder.sh script instead" +sleep 2 +./docsbuilder.sh -p