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 # Interface from Jenkins to this script is:
  44 #  * the location of this script file,
  45 #  * the first argument is the build type ("gerrit" or "nightly"),
  46 #  * any additional arguments should be of form -Dxxx=yyy and are passed
  47 #    to CMake to specify details related to Jenkins configuration, such as the
  48 #    locations of the needed executables (e.g., DOXYGEN_EXECUTABLE).
  49 #
  50 # Communication back to Jenkins is through
  51 #  * return value of this script (non-zero marks the build failed).
  52 #  * stdout (any instance of "FAILED" marks the build unstable),
  53 #  * HTML documentation produced at build/docs/html/, and
  54 #  * log files under build/docs/logs/:
  55 #     - all .log files from this directory are published as Jenkins artifacts
  56 #     - all .log files under doxygen/ subdir are scanned for Doxygen warnings
  57 #     - all .log files under sphinx/ subdir are scanned for Sphinx warnings
  58
  59 function usage() {
  60     echo "usage: build-docs.sh gerrit|nightly [-D...=...]*"
  61     echo "All additional options (-D etc.) are passed to CMake"
  62 }
  63
  64 GERRIT_MODE=
  65 NIGHTLY_MODE=
  66 case "$1" in
  67     gerrit)
  68         GERRIT_MODE=1
  69         ;;
  70     nightly)
  71         NIGHTLY_MODE=1
  72         ;;
  73     *)
  74         usage
  75         exit 2
  76         ;;
  77 esac
  78 shift
  79
  80 set -x
  81
  82 srcdir=`git rev-parse --show-toplevel`
  83 cd $srcdir
  84 if [ ! -f "admin/build-docs.sh" ] ; then
  85     echo "Failed to find root of the source tree"
  86     exit 1
  87 fi
  88
  89 # Some of the documentation targets can only be built out of source.
  90 rm -rf build
  91 mkdir build
  92 cd build
  93
  94 # Make a configuration that is fast, just for building docs.
  95 cmake ..  "$@" \
  96     -DGMX_BUILD_HELP=yes -DGMX_BUILD_MANUAL=yes \
  97     -DCMAKE_BUILD_TYPE=Debug -DGMX_OPENMP=off -DGMX_SIMD=None -DGMX_GPU=no
  98
  99 # Need to make gmx to export rst help.
 100 make gmx -j 2 || echo "FAILED to make gmx"
 101
 102 # webpage target makes all the documentation components.
 103 make webpage || echo "FAILED to make webpage"
 104
 105 # Ideally, we would also make the other components individually, to check
 106 # that the targets still work, but most of them duplicate the build
 107
 108 grep "LaTeX Warning: Reference .* on page .* undefined" docs/manual/gromacs.log && echo "FAILED - undefined references in manual"
 109
 110 # run check-source
 111 if [[ $GERRIT_MODE ]] ; then
 112     make check-source || echo "FAILED: check-source found errors"
 113 fi
 114
 115 # Copy the output logs to a static hierarchy to allow changing the exact file
 116 # names and adding new logs without changing the Jenkins job configuration.
 117 mkdir docs/logs
 118 cp docs/manual/manual.log docs/logs/
 119 mkdir docs/logs/doxygen
 120 cp docs/doxygen/*.log docs/logs/doxygen/
 121 mkdir docs/logs/sphinx
 122 cp docs/sphinx-*.log docs/logs/sphinx/
 123
 124 cd ..
 125
 126 if [ -f build/docs/html/index.html ] ; then
 127     linkchecker build/docs/html/index.html -f docs/linkcheckerrc \
 128         --ignore-url html-full --ignore-url html-user --ignore-url html-lib \
 129         --ignore-url .tar.gz --ignore-url _sources
 130       # add this to previous line once content stabilizes
 131       # || echo "FAILED linkchecker"
 132 else
 133     echo "No build/docs/html/index.html was made; can't check links!"
 134 fi
 135
 136 # Exit with zero code to avoid failing builds because of whatever was the last
 137 # command executed.
 138 exit 0