Merge branch 'doc' into 'main'

Enhanvcement of CI, enabling doxygen doc generation

See merge request sec34/port!20

.gitlab-ci.yml

@@ -34,6 +34,8 @@ build-poet:       # This job runs in the build stage, which runs first.
     - mkdir build && cd build
     - cmake ..
     - make -j$(nproc)
+  rules:
+    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
 
 test-poet:
   stage: test
@@ -41,6 +43,8 @@ test-poet:
     - mkdir build_test && cd build_test
     - cmake -DPOET_ENABLE_TESTING=ON ..
     - make -j$(nproc) check
+  rules:
+    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
 
 archive-sources:       # This job runs in the build stage, which runs first.
   image: python:3
@@ -93,3 +97,18 @@ release-create:
       links:
         - name: '${SOURCE_ARCHIVE_NAME}'
           url: 'https://git.gfz-potsdam.de/sec34/port/-/jobs/${ARCHIVE_JOB_ID}/artifacts/file/${SOURCE_ARCHIVE_NAME}'
+
+create-docs:
+  stage: release
+  before_script:
+    - apt-get update && apt-get install -y doxygen graphviz
+    - mkdir {public,build}
+  script:
+    - pushd build
+    - cmake .. && make doxygen && ls -alh docs
+    - popd && mv build/docs/html/* public/
+  artifacts:
+    paths:
+      - public
+  rules:
+    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

CMakeLists.txt

@@ -1,7 +1,9 @@
 # Version 3.9+ offers new MPI package variables
 cmake_minimum_required(VERSION 3.9)
 
-project(POET CXX C)
+project(POET
+  LANGUAGES CXX C
+  DESCRIPTION "A coupled reactive transport simulator")
 
 # specify the C++ standard
 set(CMAKE_CXX_STANDARD 17)
@@ -39,6 +41,4 @@ endif()
 
 option(BUILD_DOC "Build documentation with doxygen" OFF)
 
-if(BUILD_DOC)
-  add_subdirectory(docs)
-endif(BUILD_DOC)
+add_subdirectory(docs)

app/CMakeLists.txt

@@ -1,7 +1,3 @@
-set(SRC_CODE_DIR
-    ${CMAKE_CURRENT_SOURCE_DIR}
-    CACHE INTERNAL "directory indicating which source code version is used")
-
 get_poet_version()
 
 configure_file(poet.h.in poet.h)

docs/CMakeLists.txt

@@ -1,18 +1,18 @@
 find_package(Doxygen)
+
 if(DOXYGEN_FOUND)
+  set(DOXYGEN_GENERATE_HTML YES)
+  set(DOXYGEN_EXCLUDE_PATTERNS ${PROJECT_SOURCE_DIR}/*/argh.hpp)
+  set(DOXYGEN_USE_MDFILE_AS_MAINPAGE ${PROJECT_SOURCE_DIR}/README.md)
 
-  set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/./Doxyfile.in)
-  set(DOXYGEN_OUT ${CMAKE_BINARY_DIR}/Doxyfile)
+  # See https://www.doxygen.nl/manual/customize.html
+  set(DOXYGEN_DISABLE_INDEX NO)
+  set(DOXYGEN_GENERATE_TREEVIEW YES)
+  set(DOXYGEN_FULL_SIDEBAR YES)
 
-  configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
-
-  add_custom_target(doc_doxygen ALL
-    COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
-    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-    COMMENT "Generating documantation with doxygen"
-    VERBATIM)
-
-  install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen/ DESTINATION docs)
-else(DOXYGEN_FOUND)
-  message("Doxygen not found. Please install.")
-endif(DOXYGEN_FOUND)
+  doxygen_add_docs(doxygen
+    ${PROJECT_SOURCE_DIR}/include
+    ${PROJECT_SOURCE_DIR}/README.md
+    ${PROJECT_SOURCE_DIR}/docs/Output.md
+    COMMENT "Generate html pages")
+endif()