Commit 48133574 authored by Santiago Ospina De Los Ríos's avatar Santiago Ospina De Los Ríos

Merge branch '158-use-simple-doc-server-to-deploy-dorie-docs' into 'master'

Resolve "Use simple doc server to deploy DORiE docs"

Closes #158

See merge request !163
parents d33b4473 b87ae133
......@@ -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
......@@ -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.
......
......@@ -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.
......
......@@ -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
......@@ -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 \
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment