[ci] [docs] deploy code-reference to eos using gitlab

* Replaces the existing travis / github pages workflow for doxygen
* fixes the diagram and its installation
* renames the cmake option to controll the doc generation to BUILD_DOCS
  as this is more generic and widely used

.gitlab-ci.yml

@@ -0,0 +1,69 @@
+
+# -- Gitlab CI configuration for EDM4HEP -----------------------------
+# 
+# This file configures the deployment of the code reference generated 
+# by doxygen to a web site. The site produced in the generate-docs
+# is static and relocatable, the html files can simply be hosted by any
+# server. Here, the CERN gitlab and eos infrastructure is used to publish
+# to https://edm4hep.web.cern.ch (shorter alias: cern.ch/edm4hep)
+
+
+# -- Run Doxygen ------------------------------ 
+# Doxygen is set up in CMake, so need to load all
+# dependencies to run it. This step requires a runner
+# that can build edm4hep and run doxygen. The easiest way to
+# ensure this is require cvmfs access on the runner and take the
+# software from there. 
+generate-docs:
+  # need a runner with cvmfs installed. On the CERN gitlab instance,
+  # these are usually tagged with "cvmfs"
+  tags:
+   - cvmfs
+  script:
+    # use a setup that provides all dependencies - if the dependencies change,
+    # this needs to be updated
+    - source /cvmfs/sft.cern.ch/lcg/views/LCG_99/x86_64-centos7-gcc8-opt/setup.sh 
+    - mkdir build; cd build;
+    # the documentation option is off by default, explicitly switch it on
+    - cmake .. -DBUILD_DOCS=ON
+    - make doc
+  # make the build folder (which includes the generated html) accessible to the next step by declaring it
+  # as an artifact
+  artifacts:
+    paths:
+      - build
+    expire_in: 1 week
+
+
+
+# -- Deploy to EOS ---------------------------- 
+# Use the standard workflow to publish to eos
+# see https://gitlab.cern.ch/ci-tools/ci-web-deployer
+# The variables for this particular deployment:
+# CI_OUTPUT_DIR: build/doxygen/html/
+# EOS_ACCOUNT_PASSWORD: xxx
+# EOS_ACCOUNT_USERNAME: xxx
+# EOS_PATH: /eos/project-k/key4hep/www/edm4hep/
+# METHOD: rsync
+# are set in the repository https://gitlab.cern.ch/key4hep/edm4hep,
+# which mirrors https://github.com/key4hep/edm4hep
+# In particular, the service account key4hep is used to write
+# to the eos space /eos/project/k/key4hep/www/edm4hep
+# Other accounts which are part of the e-groups 
+# cernbox-project-key4hep-{readers|writers} may be used.
+# The eos path and website are configured using https://webeos.cern.ch/
+deployment:
+  # make sure that changes are deployed only when they are merged to master
+  only:
+    refs:
+      - master
+  # need the doxygen artifacts for this step
+  dependencies:
+    - generate-docs
+  stage: deploy
+  # see see https://gitlab.cern.ch/ci-tools/ci-web-deployer
+  image: gitlab-registry.cern.ch/ci-tools/ci-web-deployer:latest
+  script:
+    - deploy-eos
+  before_script: []
+  after_script: []

.travis.yml

@@ -72,13 +72,6 @@ script:
 
 
 
-after_success:
-  # Generate the docs only if master, the travis_build_docs is true and we can use secure variables
-  - >-
-    if [[ "$TRAVIS_BRANCH" = "master" && "$TRAVIS_PULL_REQUEST" = "false" ]] ; then
-
-       cd ${PKGDIR}; docker exec -ti CI_CONTAINER  /bin/bash -c "cd /workspace; source init.sh; cd build; ninja  doc" && ./.edm4hep-ci.d/generateDocumentation.sh || travis_terminate 1
-    fi
 
 # Don't send e-mail notifications
 notifications:

CMakeLists.txt

@@ -64,7 +64,7 @@ set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DDROP_CGAL")
 
 #--- Declare options -----------------------------------------------------------
 
-option(EDM4HEP_DOCUMENTATION "Whether or not to create doxygen doc target.")
+option(BUILD_DOCS "Whether or not to create doxygen doc target.")
 
 #--- enable unit testing capabilities ------------------------------------------
 include(CTest)
@@ -76,8 +76,13 @@ if(ENABLE_CPACK)
 endif()
 
 #--- target for Doxygen documentation ------------------------------------------
-if(EDM4HEP_DOCUMENTATION)
+if(BUILD_DOCS)
   include(cmake/EDM4HEPDoxygen.cmake)
+  # copy images needed for documentation to build folder and install them
+  configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doc/edm4hep_diagram.svg
+                 ${CMAKE_CURRENT_BINARY_DIR}/doxygen/html/doc/edm4hep_diagram.svg COPYONLY)
+  install(FILES ${CMAKE_CURRENT_BINARY_DIR}/doxygen/html/doc/edm4hep_diagram.svg
+          DESTINATION ${CMAKE_INSTALL_DOCDIR})
 endif()
 
 #--- add version files ---------------------------------------------------------

README.md

@@ -6,7 +6,7 @@
 
 A generic event data model for future HEP collider experiments.
 
-![](https://key4hep.github.io/EDM4hep/doc/edm4hep_diagram.svg)
+![](doc/edm4hep_diagram.svg)
 
 
 

doc/Doxyfile.in

@@ -838,7 +838,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             =
+IMAGE_PATH             = @CMAKE_SOURCE_DIR@
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program