Sphinx - Build on Change

Zum schreiben von Dokumentation ist es hilfreich das watchdog Python-Utility zu nutzen.

Diese Seite wird (lokal) mit einem Shell-Script zusammenschraubt, so kann ich beim schreiben gleich das Ergebnis begutachten.

Bitte das Script an die eigenen Bedürfnisse anpassen.

 1#!/usr/bin/env bash
 2
 3# figure out where we live
 4SELF_DIR=$(cd "$(dirname "$0")" || exit 1; pwd)
 5
 6_usage() {
 7    # prints help with command line flags
 8    echo -e "$0 build, clean, browse and rebuild on change
 9\nflags:
10\t       \t\t build
11\t -b/-w \t\t open in browser
12\t -c/-s \t\t clean (before build)
13\t -l/-r \t\t rebuild on file changes
14"
15}
16
17_make() {
18    # finds correct make command for platform
19    local res="make"
20    if command -v gmake >/dev/null; then res="gmake"; fi
21    echo -n "$res"
22}
23
24web_browse() {
25    # calls python's webbrowser module to open freshly built files
26    local html=$1
27    [[ -f "$html" ]] && python3 -m webbrowser -t "file://$html"
28}
29
30build_loop() {
31    # runs the build command in a loop on file change
32    local command=$1
33    watchmedo shell-command "$SELF_DIR" \
34        --recursive \
35        --ignore-directories \
36        --drop \
37        --patterns="*.rst;*.sh" \
38        --command="clear; $command; date"
39}
40
41# preset default actions here
42DO_CLEAN=""
43DO_BUILD="$(_make) html"
44DO_VISIT=""
45DO_CYCLE=""
46
47# parse command options and put them into the actions
48while getopts ":bchlrsw" OPTION; do
49    case $OPTION in
50        b|w) DO_VISIT="$SELF_DIR/_build/html/index.html" ;;
51        c|s) DO_CLEAN="$(_make) clean" ;;
52        l|r) DO_CYCLE=$DO_BUILD ;;
53        h) _usage; exit 0 ;;
54        ?) _usage; exit 1 ;;
55    esac
56done
57
58# finally run all set actions
59[[ -n "$DO_CLEAN" ]] && $DO_CLEAN
60[[ -n "$DO_BUILD" ]] && $DO_BUILD
61[[ -n "$DO_VISIT" ]] && web_browse "$DO_VISIT"
62[[ -n "$DO_CYCLE" ]] && {
63    test -n "$DO_CLEAN" && DO_CYCLE="$DO_CLEAN; $DO_CYCLE"
64    build_loop "$DO_CYCLE"
65}
66
67exit 0