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
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
#!/usr/bin/env bash

# figure out where we live
SELF_DIR=$(cd "$(dirname "$0")" || exit 1; pwd)

_usage() {
    # prints help with command line flags
    echo -e "$0 build, clean, browse and rebuild on change
\nflags:
\t       \t\t build
\t -b/-w \t\t open in browser
\t -c/-s \t\t clean (before build)
\t -l/-r \t\t rebuild on file changes
"
}

_make() {
    # finds correct make command for platform
    local res="make"
    if command -v gmake >/dev/null; then res="gmake"; fi
    echo -n "$res"
}

web_browse() {
    # calls python's webbrowser module to open freshly built files
    local html=$1
    [[ -f "$html" ]] && python3 -m webbrowser -t "file://$html"
}

build_loop() {
    # runs the build command in a loop on file change
    local command=$1
    watchmedo shell-command "$SELF_DIR" \
        --recursive \
        --ignore-directories \
        --drop \
        --patterns="*.rst;*.sh" \
        --command="clear; $command; date"
}

# preset default actions here
DO_CLEAN=""
DO_BUILD="$(_make) html"
DO_VISIT=""
DO_CYCLE=""

# parse command options and put them into the actions
while getopts ":bchlrsw" OPTION; do
    case $OPTION in
        b|w) DO_VISIT="$SELF_DIR/_build/html/index.html" ;;
        c|s) DO_CLEAN="$(_make) clean" ;;
        l|r) DO_CYCLE=$DO_BUILD ;;
        h) _usage; exit 0 ;;
        ?) _usage; exit 1 ;;
    esac
done

# finally run all set actions
[[ -n "$DO_CLEAN" ]] && $DO_CLEAN
[[ -n "$DO_BUILD" ]] && $DO_BUILD
[[ -n "$DO_VISIT" ]] && web_browse "$DO_VISIT"
[[ -n "$DO_CYCLE" ]] && {
    test -n "$DO_CLEAN" && DO_CYCLE="$DO_CLEAN; $DO_CYCLE"
    build_loop "$DO_CYCLE"
}

exit 0