#2: add documentation

ci/config.yaml

@@ -1,19 +1,21 @@
-# Configuration of the desired CI target platforms
-# This way to separate environment definitions and runner definitions open the possibility run an environment on different runners
-#
-# This file defines all the configurations to test in CI
-# NOTE: This is an investigation about a more complex but more scalable way to difine th platforms to target in CI.
-# This file might be used as an input to scripts to
-# - generate dockerfile environment files (for nodes with type='docker-image') and being able to build and push images
-# - generate Github workflows yaml files stub (for nodes with type='github-runner')*
-# - generate Azure pipelines yaml files stub (for nodes with type='azure-runner')*
-# *In VT we have some specific stuff. We might want to add some compose logic with some generated pipeline stub and complementary
-# project-specific pipeline
+# CI Configuration describing in a centralized place all the DARMA test configurations
+# that can be used by different projects.
 
-# THIS IS A LOT OF WORK BUT MIGHT BE VERY USEFUL
+# This configuration defines the build and testing platforms for each C++ or Python projects
+# It defines 
+# - Setup:           describes setup dependencies for each testing platform
+# - Docker images:   describes Docker images and which setup should be used when building the image
+#                    WIP: make it generic as it is not in vt
+# - Runners:         describes CI matrices. Each CI matrix can be associated to a Docker image or not
+#                    If not docker image is used then CI environment should be setup on the runner when a CI workflow is triggered.
+
+# This file is used as input to
+# - generate docker images
+# - generate setup scripts for each CI environment
+# - generate matrix files listing all environments to test.
+# Setup scripts & dependencies scripts can be retrieved by any project from this repository
 
 defaults:
-  # default packages
   apt-packages: &apt-packages [
     curl, jq, less, libomp5, libunwind-dev make-guile, ninja-build,
     valgrind, zlib1g, zlib1g-dev, ccache, python3
@@ -40,14 +42,6 @@ defaults:
     ["3.11", *pip-packages], ["3.12", *pip-packages]
   ]
 
-
-# compilers:
-#   clang-11: &clang-11 { type: clang, cc: clang-11, cxx: clang++-11, fc: flang-11, gcov: llvm-gcov }
-#   gcc-9: &gcc-9 { type: gnu, cc: gcc-9, cxx: g++-9, fc: gfortran-9, gcov: gcov-9 }
-#   gcc-11: &gcc-11 { type: gnu, cc: gcc-11, cxx: g++-11, fc: gfortran-11, gcov: gcov-11 }
-#   gcc-12: &gcc-12 { type: gnu, cc: gcc-12, cxx: g++-12, fc: gfortran-12, gcov: gcov-12 }
-#   gcc-13: &gcc-13 { type: gnu, cc: gcc-13, cxx: g++-13, fc: gfortran-13, gcov: gcov-13 }
-
 setup:
   macos-14-clang-14:
     label: macos-14-arm64, clang-14
@@ -77,7 +71,7 @@ setup:
       GCOV: gcov
     # deps and versions to find in vt
     deps:
-      packages: !extend [*apt-packages, gcc-9, g++-9]
+      packages: !extend [ *apt-packages, gcc-9, g++-9 ]
       cmake: *cmake-args # 3.23.4 in vt but seems to be an error with vtk tiff build because error in Cmake CheckSize.
       openmpi: *openmpi-args
       zoltan: *zoltan-args