Add a Travis CI to verify docstrings

Introduce a new DO environment variable to our Travis scripts that
specifies "what to do".  This variable can take a list of values,
including "apidocs" and "distcheck".

apidocs triggers the run of Doxygen to validate the docstrings in
the code (without actually building anything).

distcheck runs the current behavior of validating the build.

We will rely on the output of this build to ensure that the docstrings
are valid at branch merge time.  Running Doxygen locally on every
change has become too cumbersome due to the resources consumed by
Doxygen on our large source tree.

.travis.yml

@@ -8,19 +8,22 @@ before_install:
     - ./admin/travis-install-deps.sh
 
 env:
-    - AS_ROOT=no
-    - AS_ROOT=yes UNPRIVILEGED_USER=no
-    - AS_ROOT=yes UNPRIVILEGED_USER=yes
+    - DO=apidocs
+    - DO=distcheck AS_ROOT=no
+    - DO=distcheck AS_ROOT=yes UNPRIVILEGED_USER=no
+    - DO=distcheck AS_ROOT=yes UNPRIVILEGED_USER=yes
 
 matrix:
     exclude:
         # Treat clang as the main compiler.  For gcc, just run the AS_ROOT=no
         # env above to see if we can actually build, but do not really worry
         # about the run-time aspects of the tests.
         - compiler: gcc
-          env: AS_ROOT=yes UNPRIVILEGED_USER=no
+          env: DO=apidocs
         - compiler: gcc
-          env: AS_ROOT=yes UNPRIVILEGED_USER=yes
+          env: DO=distcheck AS_ROOT=yes UNPRIVILEGED_USER=no
+        - compiler: gcc
+          env: DO=distcheck AS_ROOT=yes UNPRIVILEGED_USER=yes
 
 script:
     - ./admin/travis-build.sh

admin/travis-build.sh

@@ -29,30 +29,53 @@
 
 set -e -x
 
-if [ -d /usr/local/share/aclocal ]; then
-    autoreconf -isv -I/usr/local/share/aclocal
-else
-    autoreconf -isv
-fi
-./configure
+run_configure() {
+    if [ -d /usr/local/share/aclocal ]; then
+        autoreconf -isv -I/usr/local/share/aclocal
+    else
+        autoreconf -isv
+    fi
+    ./configure "${@}"
+}
+
+do_apidocs() {
+    run_configure --enable-doxygen || return 1
+    make check-api-docs
+}
+
+do_distcheck() {
+    run_configure || return 1
 
-f=
-f="${f} CPPFLAGS='-I/usr/local/include'"
-f="${f} LDFLAGS='-L/usr/local/lib -Wl,-R/usr/local/lib'"
-f="${f} PKG_CONFIG_PATH='/usr/local/lib/pkgconfig'"
-if [ "${AS_ROOT:-no}" = yes ]; then
-    config_file=
-    if [ "${UNPRIVILEGED_USER:-no}" = yes ]; then
-        cat >root-kyua.conf <<EOF
+    local f=
+    f="${f} CPPFLAGS='-I/usr/local/include'"
+    f="${f} LDFLAGS='-L/usr/local/lib -Wl,-R/usr/local/lib'"
+    f="${f} PKG_CONFIG_PATH='/usr/local/lib/pkgconfig'"
+    if [ "${AS_ROOT:-no}" = yes ]; then
+        local config_file=
+        if [ "${UNPRIVILEGED_USER:-no}" = yes ]; then
+            cat >root-kyua.conf <<EOF
 syntax(2)
 unprivileged_user = 'nobody'
 EOF
-        config_file="$(pwd)/root-kyua.conf"
+            config_file="$(pwd)/root-kyua.conf"
+        else
+            config_file=none
+        fi
+        sudo -H make distcheck DISTCHECK_CONFIGURE_FLAGS="${f}" \
+            KYUA_TEST_CONFIG_FILE="${config_file}"
     else
-        config_file=none
+        make distcheck DISTCHECK_CONFIGURE_FLAGS="${f}"
     fi
-    sudo -H make distcheck DISTCHECK_CONFIGURE_FLAGS="${f}" \
-        KYUA_TEST_CONFIG_FILE="${config_file}"
-else
-    make distcheck DISTCHECK_CONFIGURE_FLAGS="${f}"
-fi
+}
+
+main() {
+    if [ -z "${DO}" ]; then
+        echo "DO must be defined" 1>&2
+        exit 1
+    fi
+    for step in ${DO}; do
+        "do_${DO}" || exit 1
+    done
+}
+
+main "${@}"

admin/travis-install-deps.sh

@@ -67,9 +67,32 @@ install_from_bintray() {
     rm -f "${name}"
 }
 
-if ! install_from_bintray; then
-    install_from_github atf atf 0.20
-    install_from_github lutok lutok 0.4
-    install_from_github kyua kyua-testers 0.2
-    install_from_github kyua kyua-cli 0.8
-fi
+install_configure_deps() {
+    if ! install_from_bintray; then
+        install_from_github atf atf 0.20
+        install_from_github lutok lutok 0.4
+        install_from_github kyua kyua-testers 0.2
+        install_from_github kyua kyua-cli 0.8
+    fi
+}
+
+do_apidocs() {
+    sudo apt-get install -y doxygen
+    install_configure_deps
+}
+
+do_distcheck() {
+    install_configure_deps
+}
+
+main() {
+    if [ -z "${DO}" ]; then
+        echo "DO must be defined" 1>&2
+        exit 1
+    fi
+    for step in ${DO}; do
+        "do_${DO}" || exit 1
+    done
+}
+
+main "${@}"