Add CI workflow for building new documentation

.ci/build-kit/scripts/build_docs.sh

@@ -0,0 +1,29 @@
+#!/bin/sh
+
+TRAILBOOK_everest_IS_RELEASE=${TRAILBOOK_everest_IS_RELEASE:-"OFF"}
+TRAILBOOK_everest_INSTANCE_NAME=${TRAILBOOK_everest_INSTANCE_NAME:-"nightly"}
+TRAILBOOK_everest_OVERWRITE_EXISTING_INSTANCE=${TRAILBOOK_everest_OVERWRITE_EXISTING_INSTANCE:-"OFF"}
+
+cmake \
+    -B "$EXT_MOUNT/build" \
+    -S "$EXT_MOUNT/source" \
+    -G Ninja \
+    -D EVC_ENABLE_CCACHE=ON \
+    -D EVEREST_ENABLE_COMPILE_WARNINGS=ON \
+    -D EVEREST_BUILD_DOCS=ON \
+    -D TRAILBOOK_everest_DOWNLOAD_ALL_VERSIONS=ON \
+    -D TRAILBOOK_everest_IS_RELEASE=$TRAILBOOK_everest_IS_RELEASE \
+    -D TRAILBOOK_everest_INSTANCE_NAME="$TRAILBOOK_everest_INSTANCE_NAME" \
+    -D TRAILBOOK_everest_OVERWRITE_EXISTING_INSTANCE=$TRAILBOOK_everest_OVERWRITE_EXISTING_INSTANCE
+retVal=$?
+if [ $retVal -ne 0 ]; then
+    echo "Configuring failed with return code $retVal"
+    exit $retVal
+fi
+
+ninja -C "$EXT_MOUNT/build" trailbook_everest
+retVal=$?
+if [ $retVal -ne 0 ]; then
+    echo "Compiling failed with return code $retVal"
+    exit $retVal
+fi

.ci/build-kit/scripts/install.sh

@@ -1,6 +1,6 @@
 #!/bin/sh
 
-ninja -C "$EXT_MOUNT/build" install
+ninja -C "$EXT_MOUNT/build" install/strip
 retVal=$?
 
 if [ $retVal -ne 0 ]; then

.github/workflows/build_and_test.yaml

@@ -30,6 +30,14 @@ jobs:
       do_not_run_coverage_badge_creation: true
       run_install_wheels: true
       run_integration_tests: true
+  build-docs:
+    name: Call Build Documentation
+    needs:
+      - ci
+    uses: ./.github/workflows/build_docs.yaml
+    with:
+      runner: ${{ inputs.runner || 'ubuntu-24.04' }}
+      deploy_docs: false
   ocpp-tests:
     name: OCPP Tests
     needs:

.github/workflows/build_docs.yaml

@@ -0,0 +1,126 @@
+name: Build Documentation
+on:
+  workflow_call:
+    inputs:
+      runner:
+        description: 'Which runner to use'
+        required: false
+        default: 'ubuntu-24.04'
+        type: string
+      use_build_cache:
+        description: 'Whether to use build cache or not'
+        required: false
+        default: true
+        type: boolean
+      build_kit_scripts_directory:
+        description: 'Directory in the repository where the build kit scripts are located'
+        required: false
+        default: '.ci/build-kit/scripts'
+        type: string
+      deploy_docs:
+        description: 'Whether to deploy the built documentation to the target repository'
+        required: false
+        default: false
+        type: boolean
+
+
+jobs:
+  build-docs:
+    name: Build EVerest Documentation
+    runs-on: ${{ inputs.runner }}
+    env:
+      SSH_AUTH_SOCK: /tmp/ssh_agent.sock
+    steps:
+      - name: Setup SSH Agent, optional with SSH key
+        env:
+          SSH_KEY: ${{ secrets.SA_GITHUB_SSH_KEY }}
+        run: |
+          ssh-agent -a $SSH_AUTH_SOCK > /dev/null
+          if [ -z "${{ env.SSH_KEY }}" ]; then
+            echo "No SSH key provided, skipping SSH key setup"
+            exit 0
+          fi
+          mkdir -p ~/.ssh
+          echo "${{ env.SSH_KEY }}" > ~/.ssh/id_ed25519
+          chmod 600 ~/.ssh/id_ed25519
+          # Check if github.com is already in known_hosts, if not, add it
+          if ! grep -q "^github.com " ~/.ssh/known_hosts; then
+            ssh-keyscan github.com >> ~/.ssh/known_hosts
+          fi
+          ssh-add ~/.ssh/id_ed25519
+      - name: Configure Git user
+        run: |
+          git config --global user.name "Pionix Github Service Account"
+          git config --global user.email "compiler@pionix.de"
+      - name: Docker Meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.BUILD_KIT_IMAGE_NAME }}
+          sep-tags: ","
+      - name: Set output tag
+        id: buildkit_tag
+        shell: python3 {0}
+        run: |
+          import os
+          tags = "${{ steps.meta.outputs.tags }}".split(",")
+          if len(tags) == 0:
+            print("No tags found!❌")
+            exit(1)
+          tag = f"local/build-kit-everest-core:{tags[0]}"
+          with open(os.environ["GITHUB_OUTPUT"], "a") as f:
+            f.write(f"tag={tag}\n")
+            print(f"Set tag={tag}")
+      - name: Download build-kit image
+        uses: actions/download-artifact@v4
+        with:
+          name: build-kit
+      - name: Load build-kit image
+        run: |
+          docker load -i build-kit.tar
+          docker image tag ${{ steps.buildkit_tag.outputs.tag }} build-kit
+      - name: Format branch name for cache key
+        if: ${{ inputs.use_build_cache == 'true' }}
+        run: |
+          BRANCH_NAME_FOR_CACHE="${GITHUB_REF_NAME//-/_}"
+          echo "branch_name_for_cache=${BRANCH_NAME_FOR_CACHE}" >> "$GITHUB_ENV"
+      - name: Setup cache
+        if: ${{ inputs.use_build_cache == 'true' }}
+        uses: actions/cache@v4
+        with:
+          path: cache
+          key: compile-${{ env.branch_name_for_cache }}-${{ github.sha }}
+          restore-keys: |
+            compile-${{ env.branch_name_for_cache }}-
+            compile-
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          path: source
+      - name: Setup run scripts
+        run: |
+          mkdir scripts
+          rsync -a source/${{ inputs.build_kit_scripts_directory }}/ scripts
+      - name: Build Documentation
+        run: |
+          docker run \
+          --mount type=bind,source=$SSH_AUTH_SOCK,target=/ssh-agent \
+          --env SSH_AUTH_SOCK=/ssh-agent \
+          --env TRAILBOOK_everest_IS_RELEASE=OFF \
+          --env TRAILBOOK_everest_INSTANCE_NAME=nightly \
+          --env TRAILBOOK_everest_OVERWRITE_EXISTING_INSTANCE=ON \
+          --volume "${{ github.workspace }}:/ext" \
+          --name build-docs-container \
+          build-kit run-script build_docs
+      - name: Upload Documentation Artifact
+        uses: actions/upload-artifact@v4.6.2
+        with:
+          if-no-files-found: error
+          path: ${{ github.workspace }}/build/docs/deployed_docs_repo/docs/
+          name: docs-html
+      - name: Deploy Documentation
+        if: ${{ inputs.deploy_docs == true }}
+        run: |
+          cd ${{ github.workspace }}/build/docs/deployed_docs_repo
+          git commit -a -m "Update nightly documentation from commit ${{ github.sha }}"
+          git push

.github/workflows/on_main.yaml

@@ -0,0 +1,29 @@
+name: Build, Lint and Test
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  ci:
+    name: Build, Lint and Test
+    uses: everest/everest-ci/.github/workflows/continuous_integration.yml@v1.4.6
+    permissions:
+      contents: read
+    secrets:
+      coverage_deploy_token: ${{ secrets.SA_GITHUB_PAT }}
+    with:
+      runner: ${{ inputs.runner || 'ubuntu-22.04' }}
+      artifact_deploy_target_repo: EVerest/everest.github.io
+      run_coverage: false
+      do_not_run_coverage_badge_creation: true
+      run_install_wheels: true
+      run_integration_tests: true
+  build-docs:
+    name: Call Build Documentation
+    needs:
+      - ci
+    uses: ./.github/workflows/build_docs.yaml
+    with:
+      runner: ${{ inputs.runner || 'ubuntu-24.04' }}
+      deploy_docs: true

CMakeLists.txt

@@ -63,9 +63,9 @@ endif()
 
 option(CREATE_SYMLINKS "Create symlinks to javascript modules and auxillary files - for development purposes" OFF)
 option(CMAKE_RUN_CLANG_TIDY "Run clang-tidy" OFF)
-option(EVEREST_BUILD_API_DOCS "Build EVerest API documentation" OFF)
 option(ISO15118_2_GENERATE_AND_INSTALL_CERTIFICATES "Automatically generate and install certificates for development purposes" ON)
 option(EVEREST_ENABLE_RUN_SCRIPT_GENERATION "Enables the generation of run scripts (convenience scripts for starting available configurations)" ON)
+option(EVEREST_BUILD_DOCS "Build EVerest documentation" OFF)
 option(${PROJECT_NAME}_BUILD_TESTING "Build unit tests, used if included as dependency" OFF)
 option(BUILD_TESTING "Build unit tests, used if standalone project" OFF)
 option(EVEREST_ENABLE_COMPILE_WARNINGS "Enable compile warnings set in the EVEREST_COMPILE_OPTIONS flag" OFF)
@@ -98,6 +98,8 @@ if(EVEREST_CORE_BUILD_TESTING)
 
     if(EVEREST_ENABLE_DEBUG_BUILD)
         set(CMAKE_BUILD_TYPE Debug CACHE STRING "Build type" FORCE)
+    else()
+        set(CMAKE_BUILD_TYPE MinSizeRel CACHE STRING "Build type" FORCE)
     endif()
 endif()
 
@@ -155,6 +157,9 @@ else()
     find_package(sdbus-c++ REQUIRED)
 endif()
 
+if(EVEREST_BUILD_DOCS)
+    add_subdirectory(docs)
+endif()
 
 include(ev-project-bootstrap)
 
@@ -171,8 +176,6 @@ add_subdirectory(lib)
 # FIXME (aw): this should be optional
 add_subdirectory(config)
 
-add_subdirectory(doc)
-
 ev_install_project()
 
 # configure clang-tidy if requested

THIRD_PARTY.md

@@ -2,3 +2,4 @@
 
 - [CodeCoverage.cmake](https://github.com/bilke/cmake-modules/blob/master/CodeCoverage.cmake) licensed under [The 3-Clause BSD License](https://opensource.org/licenses/BSD-3-Clause)
 - [Nanopb - Protocol Buffers for Embedded Systems](https://github.com/nanopb/nanopb) licensed under [The zlib License](https://opensource.org/licenses/Zlib)
+- [sphinx-notfound-page](https://github.com/readthedocs/sphinx-notfound-page) licensed under [The MIT License](https://opensource.org/licenses/MIT)

applications/utils/scripts/create_snapshot.py

@@ -44,6 +44,7 @@ def main():
     parser.add_argument('--allow-relative-to-working-dir', action='store_true', help='Allow temporary directory to be relative to working dir (dangerous!)')
     parser.add_argument('--post-process', action='store_true', help='Postprocess existing snapshot')
     parser.add_argument('--include-external-deps', action='store_true', help='Include external dependencies in snapshot')
+    parser.add_argument('--exclude-dir', action='append', dest='excluded_dirs', type=str, help='Exclude specified directory from snapshot (can be used multiple times)', default=[])
 
     args = parser.parse_args()
 
@@ -62,6 +63,12 @@ def main():
         print(f'Temporary directory cannot be relative to working directory: {tmp_dir}')
         return 1
 
+    excluded_paths = []
+    for excluded_dir in args.excluded_dirs:
+        excluded_path = working_dir / excluded_dir
+        excluded_path = excluded_path.expanduser().resolve()
+        excluded_paths.append(excluded_path)
+
     if not args.post_process and tmp_dir.exists():
         print(f'Temporary directory dir already exists, deleting it: {tmp_dir}')
         shutil.rmtree(tmp_dir, ignore_errors=True)
@@ -77,6 +84,9 @@ def main():
             if subdir_path == tmp_dir:
                 print(f'{subdir_path} is tmp dir, ignoring')
                 continue
+            if subdir_path in excluded_paths:
+                print(f'{subdir_path} is excluded, ignoring')
+                continue
             print(f'Copying {subdir_path} to {tmp_dir}')
             destdir = tmp_dir / subdir_path.name
 
@@ -113,7 +123,7 @@ def main():
             for dep_versions in versions:
                 dependency, version = dep_versions.split(':')
                 if dependency in snapshot:
-                    print(f'Overriding {dependency} version {snapshot[dependency]['git_tag']} to {version}')
+                    print(f'Overriding {dependency} version {snapshot[dependency]["git_tag"]} to {version}')
                     snapshot[dependency]['git_tag'] = version
         for dependency, entry in snapshot.items():
             git_tag = ''