Sphinx - Build on Change

Beim Dokumentation schreiben ist es ganz nützlich das watchdog Python-Utility drauf los zu lassen.

Zusammen mit einem Shell-Script, dass die Dokumentation bei Änderungen baut, und einem Auto-Refresh Browser-Plugin wird das eine runde Sache.

Hier mal exemplarisch das Script, welches mir hier diese Seite (lokal) zusammenschraubt. Bitte 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
68
#!/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
    if [ -f "$html" ]; then
        python3 -m webbrowser -t "file://$html"
    fi
}

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

# 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
test -n "$DO_CLEAN" && $DO_CLEAN
test -n "$DO_BUILD" && $DO_BUILD
test -n "$DO_VISIT" && web_browse "$DO_VISIT"
if [[ -n "$DO_CYCLE" ]]; then
    test -n "$DO_CLEAN" && DO_CYCLE="$DO_CLEAN; $DO_CYCLE"
    build_loop "$DO_CYCLE"
fi

exit 0