GH #674 Check Doxygen and Sphinx builds as part of CI

8 files changed, 46 insertions, 19 deletions

diff --git a/.travis.yml b/.travis.yml
index 5e70c8759..e7d9d1aa0 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -23,18 +23,19 @@ env:
     - secure: "Th0mBSkUCDqu+EA6F7zA6DCSDZBNunfndANyq06BwaFlj71daWWjthwYFsfg3T5N2ZmI+PsULQQpOirCnJt1lbNHhMVJwZPkW0JnjoxbSNpSI2+nHv7+GO9X9WjK0LRFawiQu8WxmLMQDA+0oR0BERSFKc3gmbuav9fDfla0dXg="
 
   matrix:
+    - BUILD_MODE="docs"
+    - BUILD_MODE="mini-shared"
+    - BUILD_MODE="mini-static"
     - BUILD_MODE="shared"
     - BUILD_MODE="static"
     - BUILD_MODE="bsi"
-    - BUILD_MODE="mini-shared"
-    - BUILD_MODE="mini-static"
+    - BUILD_MODE="sanitizer"
+    - BUILD_MODE="coverage"
     - BUILD_MODE="cross-arm32"
     - BUILD_MODE="cross-arm64"
+    - BUILD_MODE="cross-win32"
     - BUILD_MODE="cross-ppc32"
     - BUILD_MODE="cross-ppc64"
-    - BUILD_MODE="cross-win32"
-    - BUILD_MODE="coverage"
-    - BUILD_MODE="sanitizer"
     - BUILD_MODE="valgrind"
     - BUILD_MODE="sonarqube"
 
@@ -51,13 +52,16 @@ matrix:
     - os: osx
       compiler: gcc
 
-    # Run bsi, coverage, valgrind, sonarqube, sanitizer, minimized and
-    # non-ARM cross builds on Linux/gcc only. The sanitizer builds
-    # under Clang run the tests very slowly and cause CI timeouts.
+    # Run docs, bsi, coverage, valgrind, sonarqube, sanitizer,
+    # minimized and non-ARM cross builds on Linux/gcc only. The
+    # sanitizer builds under Clang run the tests very slowly and cause
+    # CI timeouts.
 
     - compiler: clang
       env: BUILD_MODE="bsi"
     - compiler: clang
+      env: BUILD_MODE="docs"
+    - compiler: clang
       env: BUILD_MODE="coverage"
     - compiler: clang
       env: BUILD_MODE="sonarqube"
diff --git a/doc/manual/building.rst b/doc/manual/building.rst
index 3ccc1ab8f..f2a545e63 100644
--- a/doc/manual/building.rst
+++ b/doc/manual/building.rst
@@ -12,6 +12,8 @@ maintainer if you would like to build Botan on such a system.
 Botan's build is controlled by configure.py, which is a `Python
 <http://www.python.org>`_ script. Python 2.6 or later is required.
 
+.. highlight:: none
+
 For the impatient, this works for most systems::
 
   $ ./configure.py [--prefix=/some/directory]
diff --git a/doc/manual/tls.rst b/doc/manual/tls.rst
index d0e63b9f8..7ef61e63d 100644
--- a/doc/manual/tls.rst
+++ b/doc/manual/tls.rst
@@ -103,7 +103,7 @@ information about the connection.
      This callback is for exerimental purposes and currently unused. It may be
      removed or modified in a future release.
 
-Versions from 1.11.0 to 1.11.30 did not have ``TLS::Callbacks` and instead
+Versions from 1.11.0 to 1.11.30 did not have ``TLS::Callbacks`` and instead
 used independent std::functions to pass the various callback functions.
 This interface is currently still included but is deprecated and will be removed
 in a future release. For the documentation for this interface, please check
@@ -223,7 +223,7 @@ TLS Clients
 .. cpp:class:: TLS::Client
 
    .. cpp:function:: Client( \
-         Callbacks& callbacks,
+         Callbacks& callbacks, \
          Session_Manager& session_manager, \
          Credentials_Manager& creds, \
          const Policy& policy, \
@@ -290,7 +290,7 @@ TLS Servers
 .. cpp:class:: TLS::Server
 
    .. cpp:function:: Server( \
-         Callbacks& callbacks,
+         Callbacks& callbacks, \
          Session_Manager& session_manager, \
          Credentials_Manager& creds, \
          const Policy& policy, \
diff --git a/src/build-data/botan.doxy.in b/src/build-data/botan.doxy.in
index 90f2b9502..770149f01 100644
--- a/src/build-data/botan.doxy.in
+++ b/src/build-data/botan.doxy.in
@@ -74,6 +74,7 @@ WARN_IF_DOC_ERROR      = YES
 WARN_NO_PARAMDOC       = YES
 WARN_FORMAT            = "$file:$line: $text"
 WARN_LOGFILE           =
+WARN_AS_ERROR          = YES
 
 #---------------------------------------------------------------------------
 # configuration options related to the input files
diff --git a/src/build-data/sphinx/conf.py b/src/build-data/sphinx/conf.py
index ff927c8bd..e144944f3 100644
--- a/src/build-data/sphinx/conf.py
+++ b/src/build-data/sphinx/conf.py
@@ -214,7 +214,7 @@ latex_documents = [
 latex_show_pagerefs = False
 
 # If true, show URL addresses after external links.
-latex_show_urls = False
+latex_show_urls = 'inline'
 
 # Additional stuff for the LaTeX preamble.
 #latex_preamble = ''
diff --git a/src/lib/cert/x509/x509path.h b/src/lib/cert/x509/x509path.h
index b33069f72..f65652e59 100644
--- a/src/lib/cert/x509/x509path.h
+++ b/src/lib/cert/x509/x509path.h
@@ -169,6 +169,7 @@ class BOTAN_DLL Path_Validation_Result
 * @param certstores list of certificate stores that contain trusted certificates
 * @param hostname if not empty, compared against the DNS name in end_certs[0]
 * @param usage if not set to UNSPECIFIED, compared against the key usage in end_certs[0]
+* @param validation_time what reference time to use for validation
 * @return result of the path validation
 */
 Path_Validation_Result BOTAN_DLL x509_path_validate(
@@ -186,6 +187,7 @@ Path_Validation_Result BOTAN_DLL x509_path_validate(
 * @param certstores list of stores that contain trusted certificates
 * @param hostname if not empty, compared against the DNS name in end_cert
 * @param usage if not set to UNSPECIFIED, compared against the key usage in end_cert
+* @param validation_time what reference time to use for validation
 * @return result of the path validation
 */
 Path_Validation_Result BOTAN_DLL x509_path_validate(
@@ -203,6 +205,7 @@ Path_Validation_Result BOTAN_DLL x509_path_validate(
 * @param store store that contains trusted certificates
 * @param hostname if not empty, compared against the DNS name in end_cert
 * @param usage if not set to UNSPECIFIED, compared against the key usage in end_cert
+* @param validation_time what reference time to use for validation
 * @return result of the path validation
 */
 Path_Validation_Result BOTAN_DLL x509_path_validate(
@@ -220,6 +223,7 @@ Path_Validation_Result BOTAN_DLL x509_path_validate(
 * @param store store that contains trusted certificates
 * @param hostname if not empty, compared against the DNS name in end_certs[0]
 * @param usage if not set to UNSPECIFIED, compared against the key usage in end_certs[0]
+* @param validation_time what reference time to use for validation
 * @return result of the path validation
 */
 Path_Validation_Result BOTAN_DLL x509_path_validate(
diff --git a/src/scripts/ci/travis/build.sh b/src/scripts/ci/travis/build.sh
index 53c8df15a..3b34f7320 100755
--- a/src/scripts/ci/travis/build.sh
+++ b/src/scripts/ci/travis/build.sh
@@ -116,8 +116,14 @@ fi
 ccache --show-stats
 
 # build!
-echo $MAKE_PREFIX make -j $BUILD_JOBS
-time $MAKE_PREFIX make -j $BUILD_JOBS
+
+if [ "$BUILD_MODE" = "docs" ]; then
+    doxygen build/botan.doxy
+    sphinx-build -a -W -c src/build-data/sphinx doc/manual manual-out
+else
+    echo $MAKE_PREFIX make -j $BUILD_JOBS
+    time $MAKE_PREFIX make -j $BUILD_JOBS
+fi
 
 # post-build ccache stats
 ccache --show-stats
@@ -151,8 +157,8 @@ if [ "$BUILD_MODE" = "sonarqube" ]; then
        # When neither on master branch nor on a non-external pull request => nothing to do
     fi
 
-if [ "$BUILD_MODE" == "sonarqube" ] || \
-       ( [ "${BUILD_MODE:0:5}" == "cross" ] && [ "$TRAVIS_OS_NAME" == "osx" ] ); then
+if [ "$BUILD_MODE" = "sonarqube" ] || [ "$BUILD_MODE" = "docs" ] || \
+       ( [ "${BUILD_MODE:0:5}" = "cross" ] && [ "$TRAVIS_OS_NAME" = "osx" ] ); then
     echo "Running tests disabled on this build type"
 else
     echo Running $TEST_PREFIX $TEST_EXE
@@ -170,5 +176,7 @@ then
     done
 fi
 
-# Test make install
-make install
+if [ "$BUILD_MODE" != "docs" ]; then
+    # Test make install
+    make install
+fi
diff --git a/src/scripts/ci/travis/install.sh b/src/scripts/ci/travis/install.sh
index 9459e448d..30c54fdbe 100755
--- a/src/scripts/ci/travis/install.sh
+++ b/src/scripts/ci/travis/install.sh
@@ -19,8 +19,16 @@ if [ "$BUILD_MODE" = "sonarqube" ]; then
 fi
 
 if [ "$TRAVIS_OS_NAME" = "linux" ]; then
+    sudo apt-get -qq update
+
+    if [ "$BUILD_MODE" = "docs" ]; then
+        sudo apt-get install doxygen
+        # The version of Sphinx in 14.04 is too old (1.2.2)
+        # and does not support all C++ features used in the manual
+        sudo pip install sphinx
+    fi
+
     if [ "$BUILD_MODE" = "valgrind" ] || [ "${BUILD_MODE:0:5}" = "cross" ]; then
-        sudo apt-get -qq update
 
         if [ "$BUILD_MODE" = "valgrind" ]; then
             sudo apt-get install valgrind