Add infrastructure to publish documenation via CERN infrastructure (#572

)

* Add gitlab-ci config

* Update doxygen configuration to silence warnings

* Cleanup sphinx config

* Try with cmake infrastructure

* Be more specific about excluding build folders

Gitlab runners checkout packages under /builds/<rest> which makes
Doxygen ignore effectively everything

* Cleanup gitlab ci config and update comments

.gitlab-ci.yml

@@ -0,0 +1,71 @@
+# -- Gitlab CI configuration for podio -----------------------------
+#
+# This file configures the deployment of the code reference generated by sphinx
+# / 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://key4hep.web.cern.ch/podio/
+
+
+# -- Run the document generation ------------------------------
+#
+# We are going through the cmake infrastructure here. It is equivalent to
+# running sphinx-build manually as it is done in the github actions workflow
+# run it.
+# This step requires a runner that can build podio 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:
+    - k8s-cvmfs
+  image: registry.cern.ch/ghcr.io/key4hep/key4hep-images/alma9:latest
+  script:
+    # use the nightlies and install some dependencies on top of them
+    - source /cvmfs/sw-nightlies.hsf.org/key4hep/setup.sh
+    - export PATH=/root/.local/bin:$PATH
+    - export PYTHONPATH=/root/.local/lib/python3.10/site-packages:$PYTHONPATH
+    - python3 -m pip install -r doc/requirements.txt
+    - cmake -B build . --install-prefix=$(pwd)/install -GNinja -DENABLE_SIO=ON -DENABLE_RNTUPLE=ON -DBUILD_TESTING=OFF -DCMAKE_CXX_STANDARD=20 -DCREATE_DOC=ON
+    - cmake --build build --target documentation
+
+  # make the generated html available to the next step by declaring them as an artifact
+  # as an artifact
+  artifacts:
+    paths:
+      - build/doc/_build/html
+    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: doc_output
+# EOS_ACCOUNT_PASSWORD: xxx
+# EOS_ACCOUNT_USERNAME: xxx
+# EOS_PATH: /eos/project/k/key4hep/www/key4hep/podio
+# METHOD: rsync
+# are set in the repository https://gitlab.cern.ch/key4hep/podio,
+# which mirrors https://github.com/AIDASoft/podio
+# In particular, the service account key4hep is used to write
+# to the eos space /eos/project/k/key4hep/www/key4hep/podio
+# 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: []