admin/build-docs.sh

   1 #!/bin/bash
   2 #
   3 # This file is part of the GROMACS molecular simulation package.
   4 #
   5 # Copyright (c) 2015, by the GROMACS development team, led by
   6 # Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   7 # and including many others, as listed in the AUTHORS file in the
   8 # top-level source directory and at http://www.gromacs.org.
   9 #
  10 # GROMACS is free software; you can redistribute it and/or
  11 # modify it under the terms of the GNU Lesser General Public License
  12 # as published by the Free Software Foundation; either version 2.1
  13 # of the License, or (at your option) any later version.
  14 #
  15 # GROMACS is distributed in the hope that it will be useful,
  16 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18 # Lesser General Public License for more details.
  19 #
  20 # You should have received a copy of the GNU Lesser General Public
  21 # License along with GROMACS; if not, see
  22 # http://www.gnu.org/licenses, or write to the Free Software Foundation,
  23 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  24 #
  25 # If you want to redistribute modifications to GROMACS, please
  26 # consider that scientific software is very special. Version
  27 # control is crucial - bugs must be traceable. We will be happy to
  28 # consider code for inclusion in the official distribution, but
  29 # derived work must not be called official GROMACS. Details are found
  30 # in the README & COPYING files - if they are missing, get the
  31 # official version at http://www.gromacs.org.
  32 #
  33 # To help us fund GROMACS development, we humbly ask that you cite
  34 # the research papers on the package. Check out http://www.gromacs.org.
  35
  36 # This script is used by Gerrit to build the documentation in the
  37 # Documentation_* jobs.  The main purpose of this script is to isolate Jenkins
  38 # from the details of building the documentation, as the build system may still
  39 # evolve.  All code here is tightly tied to the build system, and the interface
  40 # to Jenkins tries to be as static as possible to avoid the need to rebase
  41 # changes because of job configuration changes.
  42 #
  43 # Command line options to use an existing build directory are provided for more
  44 # easily testing the script outside Jenkins.
  45 #
  46 # Interface from Jenkins to this script is:
  47 #  * the location of this script file,
  48 #  * the first argument is the build type ("gerrit" or "nightly"),
  49 #  * any additional arguments should be of form -Dxxx=yyy and are passed
  50 #    to CMake to specify details related to Jenkins configuration, such as the
  51 #    locations of the needed executables (e.g., DOXYGEN_EXECUTABLE).
  52 #
  53 # Communication back to Jenkins is through
  54 #  * return value of this script (non-zero marks the build failed).
  55 #  * stdout (any instance of "FAILED" marks the build unstable),
  56 #  * HTML documentation produced at build/docs/html/, and
  57 #  * log files under build/docs/logs/:
  58 #     - fail-reason.log contains a short description of what failed/was unstable
  59 #     - all .log files from this directory are published as Jenkins artifacts
  60 #     - all .log files under doxygen/ subdir are scanned for Doxygen warnings
  61 #     - all .log files under sphinx/ subdir are scanned for Sphinx warnings
  62
  63 # Parse arguments
  64 function usage() {
  65     echo "usage: build-docs.sh gerrit|nightly"
  66     echo "       [--use-build-dir=<existing build dir>] [--skip-cmake]"
  67     echo "       [--build-cmd=<build command>] [-D...=...]*"
  68     echo "All other additional options (-D etc.) are passed to CMake"
  69 }
  70
  71 declare -a cmake_args
  72
  73 build_dir=build
  74 build_cmd=make
  75 do_cmake=1
  76 GERRIT_MODE=
  77 NIGHTLY_MODE=
  78 case "$1" in
  79     gerrit)
  80         GERRIT_MODE=1
  81         ;;
  82     nightly)
  83         NIGHTLY_MODE=1
  84         ;;
  85     *)
  86         usage
  87         exit 2
  88         ;;
  89 esac
  90 shift
  91 for arg in "$@" ; do
  92     if [[ "$arg" == --use-build-dir=* ]] ; then
  93         build_dir=${arg#--use-build-dir=}
  94     elif [[ "$arg" == --build-cmd=* ]] ; then
  95         build_cmd=${arg#--build-cmd=}
  96     elif [[ "$arg" == --skip-cmake ]] ; then
  97         do_cmake=
  98     else
  99         cmake_args+=("$arg")
 100     fi
 101 done
 102
 103 log_output_dir=docs/logs
 104 unsuccessful_log=$log_output_dir/unsuccessful-reason.log
 105
 106 # Utilities for failure reporting
 107 FAILED=
 108 function report_failure() {
 109     echo "$1"
 110     echo "$1" >> $unsuccessful_log
 111     FAILED=1
 112 }
 113 function report_unstable() {
 114     echo "FAILED: $1"
 115     echo "$1" >> $unsuccessful_log
 116 }
 117 function exit_if_failed() {
 118     if [[ $FAILED ]] ; then
 119         echo "Documentation build FAILED:"
 120         cat $unsuccessful_log
 121         exit 1
 122     fi
 123 }
 124
 125 set -x
 126
 127 srcdir=`git rev-parse --show-toplevel`
 128 cd $srcdir
 129 if [ ! -f "admin/build-docs.sh" ] ; then
 130     echo "Failed to find root of the source tree"
 131     exit 1
 132 fi
 133
 134 # Some of the documentation targets can only be built out of source.
 135 mkdir -p $build_dir
 136 cd $build_dir
 137
 138 # Copy the output logs to a static hierarchy to allow changing the exact file
 139 # names and adding new logs without changing the Jenkins job configuration.
 140 mkdir -p $log_output_dir
 141 rm -f $unsuccessful_log
 142
 143 cmake_args+=("-DGMX_BUILD_HELP=ON" "-DGMX_BUILD_MANUAL=ON")
 144 if [[ $GERRIT_MODE ]] ; then
 145     cmake_args+=("-DGMX_COMPACT_DOXYGEN=ON")
 146 fi
 147 # Make a configuration that is fast, just for building docs.
 148 cmake_args+=("-DCMAKE_BUILD_TYPE=Debug" "-DGMX_OPENMP=OFF" "-DGMX_SIMD=None" "-DGMX_GPU=OFF")
 149 if [[ $do_cmake ]] ; then
 150     cmake $srcdir  "${cmake_args[@]}" || report_failure "CMake configuration failed"
 151     exit_if_failed
 152 else
 153     echo "Skipped cmake; args ${cmake_args[@]}"
 154 fi
 155
 156 # Need to make gmx to export rst help.
 157 $build_cmd gmx -j 2 || report_failure "Building gmx failed"
 158
 159 # Do various parts individually to report the errors.
 160 $build_cmd manual || report_failure "PDF manual failed to build"
 161 cp docs/manual/gromacs.log $log_output_dir/
 162 grep "LaTeX Warning: Reference .* on page .* undefined" docs/manual/gromacs.log && report_unstable "undefined references in manual"
 163
 164 $build_cmd doxygen-all || report_failure "Doxygen documentation failed to build"
 165
 166 # run check-source
 167 if [[ $GERRIT_MODE ]] ; then
 168     $build_cmd check-source || report_failure "check-source failed to run"
 169 fi
 170 mkdir $log_output_dir/doxygen
 171 cp docs/doxygen/*.log $log_output_dir/doxygen/
 172 for target in {check-source,doxygen-xml,doxygen-full,doxygen-lib,doxygen-user} ; do
 173     if [ -s $log_output_dir/doxygen/$target.log ] ; then
 174         report_unstable "$target produced warnings"
 175     fi
 176 done
 177 exit_if_failed
 178
 179 # Generate Sphinx input.
 180 $build_cmd sphinx-input || report_failure "Generating Sphinx input failed"
 181 $build_cmd sphinx-programs || report_failure "Running gmx help -export rst failed"
 182 exit_if_failed
 183
 184 # Run various Sphinx commands
 185 $build_cmd webpage-sphinx || report_failure "Sphinx: HTML generation failed"
 186 $build_cmd man || report_failure "Sphinx: man page generation failed"
 187 $build_cmd install-guide || report_failure "Sphinx: INSTALL generation failed"
 188 mkdir ${log_output_dir}/sphinx
 189 cp docs/sphinx-*.log ${log_output_dir}/sphinx/
 190 for log in {html,man,install} ; do
 191     if [ -s $log_output_dir/sphinx/sphinx-$log ] ; then
 192         case $log in
 193             html)
 194                 format="HTML"
 195                 ;;
 196             man)
 197                 format="man page"
 198                 ;;
 199             install)
 200                 format="INSTALL"
 201                 ;;
 202         esac
 203         report_unstable "Sphinx: $format generation produced warnings"
 204     fi
 205 done
 206 exit_if_failed
 207
 208 # webpage target makes some final work for the documentation.
 209 $build_cmd webpage || report_failure "webpage target failed to build"
 210
 211 cd $srcdir
 212
 213 if [ -f $build_dir/docs/html/index.html ] ; then
 214     linkchecker $build_dir/docs/html/index.html -f docs/linkcheckerrc \
 215         --ignore-url html-full --ignore-url html-user --ignore-url html-lib \
 216         --ignore-url .tar.gz --ignore-url _sources
 217       # add this to previous line once content stabilizes
 218       # || echo "FAILED linkchecker"
 219 else
 220     echo "No docs/html/index.html in $build_dir was made; can't check links!"
 221 fi
 222
 223 cd $build_dir
 224
 225 [[ -s $unsuccessful_log ]] && cat $unsuccessful_log
 226 [[ $FAILED ]] && exit 1
 227 exit 0