Deploy docs to Hermes doc server

* Add new deploy job creating an environment for every release branch,
  merge request, and the master branch.
* Add environment stop job removing the environment after it has been
  stopped (happens automatically if branch is deleted).

.gitlab-ci.yml

@@ -10,7 +10,7 @@ variables:
   BASE_IMAGE: dorie/dune-env
   # Use semantic versioning (not the version of DUNE) and bump according to
   # to whether changes are backwards-compatible or not.
-  IMAGE_VERSION: "1.2"
+  IMAGE_VERSION: "1.3"
   DUNE_ENV_IMAGE: ${BASE_IMAGE}:img-v${IMAGE_VERSION}
 
   CMAKE_FLAGS:
@@ -22,11 +22,38 @@ variables:
     -j $CPUS_MULTICORE
   RUN_IN_DUNE_ENV: $CI_PROJECT_DIR/build-cmake/run-in-dune-env
 
+  # Documentation server configuration
+  DOC_HOST: root@hermes.iup.uni-heidelberg.de
+  DOC_PORT: 2345      # ... forwards to utopia_doc_server container. root ok ;)
+  DOC_REMOTE_BASE_DIR: /var/dorie_doc
+  DOC_REMOTE_PATH: $DOC_REMOTE_BASE_DIR/$CI_COMMIT_REF_SLUG
+
 image: $DUNE_ENV_IMAGE
 
 before_script:
   - cd /opt/dune
 
+# Provide SSH access via the SSH_PRIVATE_KEY and SSH_KNOWN_HOSTS variables
+.ssh-access: &ssh_access
+  before_script:
+    # Run ssh-agent (inside the build environment)
+    - eval $(ssh-agent -s)
+
+    # Add the SSH key stored in SSH_PRIVATE_KEY variable to the agent store
+    # We're using tr to fix line endings which makes ed25519 keys work
+    # without extra base64 encoding.
+    # https://gitlab.com/gitlab-examples/ssh-private-key/issues/1#note_48526556
+    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - > /dev/null
+
+    # Create the SSH directory and give it the right permissions
+    - mkdir -p ~/.ssh
+    - chmod 700 ~/.ssh
+
+    # Add the known hosts lists to ensure this ssh connection is the right one
+    - echo "$SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts
+    - chmod 644 ~/.ssh/known_hosts
+
+
 stages:
   - setup
   - prep
@@ -143,6 +170,17 @@ build:debug-clang:
     - $DUNECONTROL --only=dorie make $MAKE_FLAGS build_unit_tests
     - $DUNECONTROL --only=dorie make $MAKE_FLAGS transport_d2_r0_t0 transport_d2_r1_t0
 
+build:docs:
+  stage: build
+  script:
+    - CMAKE_FLAGS="$CMAKE_FLAGS"
+      $DUNECONTROL --only=dorie configure
+    - $DUNECONTROL --only=dorie make doc
+  artifacts:
+    name: "$CI_JOB_NAME"
+    paths:
+      - $CI_PROJECT_DIR/build-cmake/doc
+    expire_in: 1 day
 
 # --- Tests ---
 test:system-tests: &test
@@ -217,6 +255,9 @@ deploy:dockerhub-devel: &deploy
       --build-arg BASE_IMG_VERSION=$IMAGE_VERSION --build-arg PROCNUM=$CPUS_DIND
       -t dorie/dorie:devel .
     - docker push dorie/dorie:devel
+  environment:
+    name: docker/devel
+    url: https://hub.docker.com/r/dorie/dorie
 
 deploy:dockerhub-stable:
   <<: *deploy
@@ -227,26 +268,52 @@ deploy:dockerhub-stable:
       --build-arg BASE_IMG_VERSION=$IMAGE_VERSION --build-arg PROCNUM=$CPUS_DIND
       -t dorie/dorie:$CI_COMMIT_TAG .
     - docker push dorie/dorie:$CI_COMMIT_TAG
+  environment:
+    name: docker/$CI_COMMIT_TAG
+    url: https://hub.docker.com/r/dorie/dorie
 
-deploy:sphinx-docs:
+deploy:docs:
   stage: deploy
   only:
-    - tags@dorie/dorie
+    - branches@dorie/dorie
   dependencies:
-    - build:system-tests
-  before_script:
-    # install the netfly CLI
-    - apt-get install -y golang-go golang-glide
-    - go get -d github.com/netlify/netlifyctl
-    - cd $HOME/go/src/github.com/netlify/netlifyctl/
-    - make deps build
-    - go install
-    - cd $HOME/go/bin
-  script:
-    - ./netlifyctl deploy
-      -A $NETFLY_DEPLOY_TOKEN
-      -s $NETFLY_SITE_ID
-      -P $CI_PROJECT_DIR/build-cmake/doc/html
+    - build:docs
+  needs: ["build:docs"]
+
+  <<: *ssh_access
+  script:
+    # Create the directory on the remote, removing any prior version
+    - echo "Creating remote directory $DOC_REMOTE_PATH ..."
+    - ssh -p $DOC_PORT $DOC_HOST "rm -rf $DOC_REMOTE_PATH"
+    - ssh -p $DOC_PORT $DOC_HOST "mkdir -p $DOC_REMOTE_PATH/doxygen/"
+
+    # Copy sphinx & doxygen HTML documentation to remote
+    - cd build-cmake/doc
+    - echo "Uploading documentation to $DOC_REMOTE_PATH/ ..."
+    - scp -P $DOC_PORT -pr html         $DOC_HOST:$DOC_REMOTE_PATH/
+    - scp -P $DOC_PORT -pr doxygen/html $DOC_HOST:$DOC_REMOTE_PATH/doxygen/
+
+  environment:
+    name: docs/$CI_COMMIT_REF_NAME
+    url: https://hermes.iup.uni-heidelberg.de/dorie_doc/$CI_COMMIT_REF_SLUG/html/
+    on_stop: deploy:stop_docs
+
+# This job is called when the environment is stopped, which automatically
+# happens when the respective branch is deleted
+deploy:stop_docs:
+  stage: deploy
+  when: manual
+  variables:
+    # Stop GitLab from checking out the commit again (branch is deleted)
+    GIT_STRATEGY: none
+  dependencies: []
+  needs: ["build:docs"]
+
+  <<: *ssh_access
+  script:
+    - echo "Removing remote directory $DOC_REMOTE_PATH ..."
+    - ssh -p $DOC_PORT $DOC_HOST "rm -rf $DOC_REMOTE_PATH"
+
   environment:
-    name: sphinx-docs
-    url: https://dorie-doc.netlify.com/
+    name: docs/$CI_COMMIT_REF_NAME
+    action: stop

CHANGELOG.md

@@ -155,6 +155,7 @@
 * Finite volume solver for the Richards equation !132
 * Build independent library and executable for each compile-time setting !144
 * `SimulationBase` unit test now uses Google Test !159
+* Deploy online documentation for each branch to private server !163
 
 ### Fixed
 * Solver in `RichardsSimulation` was using the wrong time variable.

README.md

@@ -210,9 +210,16 @@ The following software packages are cross-platform, so you should be able to fin
 
 ### Documentation
 
-The documentation of the latest release branch can be found [online](https://dorie-doc.netlify.com/).
+The documentation of active branches is automatically deployed to our server.
+You will find the latest [user manual](https://hermes.iup.uni-heidelberg.de/dorie_doc/master/html/)
+and [C++ code documentation](https://hermes.iup.uni-heidelberg.de/dorie_doc/master/doxygen/html/)
+there. The documentation for other branches can be accessed via the
+[overview page](https://hermes.iup.uni-heidelberg.de/dorie_doc/).
 
-The documentation can be built after DORiE has been properly configured (i.e., by calling `dunecontrol`). Note that you might have to re-configure DORiE once after installing it, because some dependencies are installed at configure time (e.g. by `dunecontrol --only=dorie configure`). To build the documentation, just run
+
+The documentation can also be built locally after DORiE has been properly
+configured following the step-by-step instructions above. To build the
+documentation, just run
 
     dunecontrol --only=dorie make doc
 
@@ -220,8 +227,9 @@ or navigate to the `dorie/build-cmake` directory and call
 
     make doc
 
-You will then find the index page of the documentation at
-`dorie/build-cmake/doc/html/index.html`.
+You will then find the index page of the Sphinx user manual at
+`dorie/build-cmake/doc/html/index.html` and the index page of the Doxygen C++
+code documentation at `dorie/build-cmake/doc/doxygen/html/index.html`.
 
 ### Run, DORiE, Run!
 DORiE provides a command line interface (CLI) for all its functions.

doc/doxygen/Doxylocal

@@ -12,6 +12,7 @@ GENERATE_XML = YES
 
 # Use MathJax to render math (leave it to the browser) instead of requiring Latex
 USE_MATHJAX = YES
+MATHJAX_RELPATH = https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.6/MathJax.js?config=TeX-MML-AM_CHTML
 
 # The EXCLUDE tag can be used to specify files and/or directories that should
 # excluded from the INPUT source files. This way you can easily exclude a
@@ -21,4 +22,4 @@ USE_MATHJAX = YES
 # EXCLUDE 	+= @top_srcdir@/...
 
 # Include documents with other extesions
-FILE_PATTERNS += *.dox
\ No newline at end of file
+FILE_PATTERNS += *.dox

docker/dune-env.dockerfile

@@ -18,10 +18,12 @@ RUN apt-get clean \
         g++ \
         gfortran \
         git \
+        graphviz \
         libatlas-base-dev \
         libfftw3-dev \
         libfftw3-mpi-dev \
         libfreetype6-dev \
+        libgraphviz-dev \
         libhdf5-mpi-dev \
         libmetis-dev \
         libmuparser-dev \