Build docs and upload to gh-pages (#1232)

For #889

.githooks/check-docs

@@ -30,7 +30,7 @@ fi
 mkdir -p ${DOCDIR} > /dev/null 2>&1
 pushd ${DOCDIR} > /dev/null 2>&1
 
-cat ${ROOT}/Doxyfile | \
+cat ${ROOT}/docs/Doxyfile | \
 sed \
     -e "s/\${LINT}/YES/" \
     -e "s!\${SOURCE}!${ROOT}!" \

.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: Documentation
+on:
+  push:
+    branches: [release/*, develop]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-20.04
+    continue-on-error: true
+    container:
+      image: rippleci/clio_ci:latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Build docs
+        run: |
+          mkdir -p build_docs && cd build_docs
+          cmake ../docs && cmake --build . --target docs
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build_docs/html
+          name: docs-develop # TODO: use x.y.z for `release/x.y.z` branches and `develop` for latest dev docs
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v3

CMake/ClioVersion.cmake

@@ -42,4 +42,4 @@ endif ()
 message(STATUS "Build version: ${VERSION}")
 set(clio_version "${VERSION}")
 
-configure_file(CMake/Build.cpp.in ${CMAKE_SOURCE_DIR}/src/main/impl/Build.cpp)
+configure_file(${CMAKE_CURRENT_LIST_DIR}/Build.cpp.in ${CMAKE_CURRENT_LIST_DIR}/../src/main/impl/Build.cpp)

CMake/Docs.cmake

@@ -1,7 +1,7 @@
 find_package(Doxygen REQUIRED)
 
 # See Doxyfile for these settings:
-set(SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
+set(SOURCE ${CMAKE_CURRENT_SOURCE_DIR}/..)
 set(USE_DOT "YES")
 set(LINT "NO")
 set(EXCLUDES "")

CMakeLists.txt

@@ -389,7 +389,7 @@ endif ()
 
 # Generate `docs` target for doxygen documentation if enabled Note: use `make docs` to generate the documentation
 if (docs)
-  include(CMake/Docs.cmake)
+  add_subdirectory(docs)
 endif ()
 
 include(CMake/install/install.cmake)

docs/CMakeLists.txt

@@ -0,0 +1,8 @@
+cmake_minimum_required(VERSION 3.16.3)
+project(docs)
+
+include(${CMAKE_CURRENT_SOURCE_DIR}/../CMake/ClioVersion.cmake)
+
+# Generate `docs` target for doxygen documentation
+# Note: use `cmake --build . --target docs` from your `build` directory to generate the documentation
+include(${CMAKE_CURRENT_SOURCE_DIR}/../CMake/Docs.cmake)