From 1bd0b5db00ec8659c53041e07784c34f8cc01add Mon Sep 17 00:00:00 2001 From: Valentin Volkl Date: Tue, 26 Jan 2021 10:44:42 +0100 Subject: [PATCH] [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 | 69 +++++++++++++++++++++++++++++++++++++++++ .travis.yml | 7 ----- CMakeLists.txt | 9 ++++-- README.md | 2 +- doc/Doxyfile.in | 2 +- doc/edm4hep_diagram.svg | 2 +- 6 files changed, 79 insertions(+), 12 deletions(-) create mode 100644 .gitlab-ci.yml diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml new file mode 100644 index 000000000..9efedce8d --- /dev/null +++ b/.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: [] diff --git a/.travis.yml b/.travis.yml index 6524cb95f..26fa81a5f 100644 --- a/.travis.yml +++ b/.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: diff --git a/CMakeLists.txt b/CMakeLists.txt index e54abafaf..c1ba099e3 100644 --- a/CMakeLists.txt +++ b/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 --------------------------------------------------------- diff --git a/README.md b/README.md index 400904646..874b8f5c8 100644 --- a/README.md +++ b/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) diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 3ff77a204..57e409769 100644 --- a/doc/Doxyfile.in +++ b/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 diff --git a/doc/edm4hep_diagram.svg b/doc/edm4hep_diagram.svg index 2190579eb..f32e46915 100644 --- a/doc/edm4hep_diagram.svg +++ b/doc/edm4hep_diagram.svg @@ -1190,7 +1190,7 @@ id="tspan2610" style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:7.76111111px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans Italic';text-align:center;text-anchor:middle;stroke-width:0.26458332" y="29.241552" - x="503.21472">EDM4hep DataModel Overview (v0.1) + x="503.21472">EDM4hep DataModel Overview (v0.3)