admin/builds/documentation.py

   1 #
   2 # This file is part of the GROMACS molecular simulation package.
   3 #
   4 # Copyright (c) 2015,2016,2017,2018,2019, by the GROMACS development team, led by
   5 # Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6 # and including many others, as listed in the AUTHORS file in the
   7 # top-level source directory and at http://www.gromacs.org.
   8 #
   9 # GROMACS is free software; you can redistribute it and/or
  10 # modify it under the terms of the GNU Lesser General Public License
  11 # as published by the Free Software Foundation; either version 2.1
  12 # of the License, or (at your option) any later version.
  13 #
  14 # GROMACS is distributed in the hope that it will be useful,
  15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17 # Lesser General Public License for more details.
  18 #
  19 # You should have received a copy of the GNU Lesser General Public
  20 # License along with GROMACS; if not, see
  21 # http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23 #
  24 # If you want to redistribute modifications to GROMACS, please
  25 # consider that scientific software is very special. Version
  26 # control is crucial - bugs must be traceable. We will be happy to
  27 # consider code for inclusion in the official distribution, but
  28 # derived work must not be called official GROMACS. Details are found
  29 # in the README & COPYING files - if they are missing, get the
  30 # official version at http://www.gromacs.org.
  31 #
  32 # To help us fund GROMACS development, we humbly ask that you cite
  33 # the research papers on the package. Check out http://www.gromacs.org.
  34
  35 import os
  36 import re
  37
  38 build_options = ['doxygen-1.8.5']
  39 build_out_of_source = True
  40
  41 extra_options = {
  42     'source-md5': Option.string
  43 }
  44
  45 def do_build(context):
  46     cmake_opts = {
  47             'GMX_BUILD_HELP': 'ON',
  48             'GMX_BUILD_MANUAL': 'ON',
  49             'SOURCE_MD5SUM': context.opts.source_md5,
  50             'CMAKE_BUILD_TYPE': 'Debug',
  51             'GMX_GPU': 'OFF',
  52             'GMX_OPENMP': 'OFF',
  53             'GMX_SIMD': 'None',
  54             'GMX_USE_RDTSCP': 'OFF'
  55         }
  56     release = (context.job_type == JobType.RELEASE)
  57     if release:
  58         cmake_opts['GMX_BUILD_TARBALL'] = 'ON'
  59     elif context.job_type == JobType.GERRIT:
  60         cmake_opts['GMX_COMPACT_DOXYGEN'] = 'ON'
  61     cmake_opts['DOXYGEN_EXECUTABLE'] = context.env.doxygen_command
  62     context.run_cmake(cmake_opts)
  63
  64     # we keep the individual build targets here to ensure some
  65     # granularity of the resulting error messages (if any).
  66     # it would be possible to run everything at once with
  67     # target=webpage, but then debugging a failed build would
  68     # become exceedingly tedious
  69     context.build_target(target='sphinx-input', parallel=True,
  70             failure_string='Generating Sphinx input failed',
  71             continue_on_failure=True)
  72     context.build_target(target='sphinx-programs', parallel=True,
  73             failure_string='Running gmx help -export rst failed',
  74             continue_on_failure=True)
  75
  76     context.build_target(target='manual', parallel=True,
  77             target_descr='PDF manual', continue_on_failure=True)
  78     logfile = os.path.join(context.workspace.build_dir, 'docs/manual/gromacs.log')
  79     if os.path.isfile(logfile):
  80         with open(logfile, 'r') as f:
  81             manual_log = f.read()
  82         if re.search(r'LaTeX Warning: Reference .* on page .* undefined', manual_log):
  83             context.mark_unstable('undefined references in PDF manual')
  84     context.publish_logs([logfile])
  85
  86     # check-source is not necessary for a release build, and building these
  87     # separately causes many of the Doxygen targets to get built twice if run
  88     # from a tarball.
  89     if not release:
  90         context.build_target(target='doxygen-all', parallel=True,
  91                 target_descr='Doxygen documentation', continue_on_failure=True)
  92         context.build_target(target='check-source', parallel=True,
  93                 failure_string='check-source failed to run', continue_on_failure=True)
  94         logs = []
  95         for target in ('check-source', 'doxygen-xml', 'doxygen-user',
  96                 'doxygen-lib', 'doxygen-full'):
  97             logfile = os.path.join(context.workspace.build_dir,
  98                     'docs/doxygen/{0}.log'.format(target))
  99             if os.path.isfile(logfile) and os.stat(logfile).st_size > 0:
 100                 context.mark_unstable('{0} produced warnings'.format(target))
 101             logs.append(logfile)
 102         context.publish_logs(logs, category='doxygen')
 103         if context.failed:
 104             return
 105
 106     if context.failed:
 107         return
 108
 109     sphinx_targets = [ ('webpage-sphinx', 'html', 'HTML') ]
 110     if not release:
 111         sphinx_targets.extend((
 112                 ('man', 'man', 'man page'),
 113                 ('install-guide', 'install', 'install-guide')
 114             ))
 115     logs = []
 116     for target, log, descr in sphinx_targets:
 117         context.build_target(target=target, parallel=True,
 118                 failure_string='Sphinx: {0} generation failed'.format(descr),
 119                 continue_on_failure=True)
 120         logfile = os.path.join(context.workspace.build_dir,
 121                 'docs/sphinx-{0}.log'.format(log))
 122         if os.path.isfile(logfile) and os.stat(logfile).st_size > 0:
 123             context.mark_unstable('Sphinx: {0} generation produced warnings'.format(descr))
 124         logs.append(logfile)
 125     context.publish_logs(logs, category='sphinx')
 126     if context.failed:
 127         return
 128
 129     context.build_target(target='webpage', parallel=True)
 130     if context.failed:
 131         return
 132
 133     ignore_urls = ['html-full', 'html-user', 'html-lib', '.tar.gz', '_sources']
 134     cmd = ['linkchecker', 'docs/html/index.html', '-f',
 135             context.workspace.get_project_dir(Project.GROMACS) + '/docs/linkcheckerrc',
 136             '-Fxml']
 137     for url in ignore_urls:
 138         cmd.extend(['--ignore-url', url])
 139
 140     context.run_cmd(cmd, ignore_failure=False)
 141
 142     logfile = os.path.join(context.workspace.build_dir,
 143         'docs/linkchecker-out.xml')
 144     if os.path.isfile(logfile):
 145         with open(logfile, 'r') as f:
 146             manual_log = f.read()
 147             if re.search(r'URLError:', manual_log):
 148                 context.mark_unstable('non resolvable URL in webpage')
 149             if re.search(r'warnings', manual_log):
 150                 context.mark_unstable('empty pages in web documentation')
 151         context.publish_logs([logfile], category='webpage')
 152
 153     if context.failed:
 154         return
 155
 156     if release:
 157         version_info = context.read_cmake_variable_file('VersionInfo.cmake')
 158         version = version_info['GMX_VERSION_STRING']
 159         package_name = 'website-' + version
 160         context.make_archive(package_name, root_dir='docs/html', prefix=package_name)