🐛 📚 Fix mermaid diagram generation on Ubuntu

Problem:
- Ubuntu 23.10 and later has security rules around running chrome, which means
  mermaid-cli can't generate diagrams without a workaround.
- See mermaid-js/mermaid-cli#730

Solution:
- Provide a puppeteer_config.json file in the docs directory which can be passed
  to mmdc by specifying an attribute in AsciiDoctor markdown.
- See https://docs.asciidoctor.org/diagram-extension/latest/diagram_types/mermaid/

Author: elbeno

.github/workflows/asciidoctor-ghpages.yml

@@ -40,7 +40,8 @@ jobs:
           node-version: 20
       - name: Install Mermaid
         run: |
-          sudo npm install -g @mermaid-js/[email protected]
+          sudo npm install -g @mermaid-js/[email protected]
+          npx puppeteer browsers install chrome-headless-shell
       - name: Install asciidoctor
         run: |
           sudo apt update

.github/workflows/test.yml

@@ -41,7 +41,8 @@ jobs:
 
       - name: Install Mermaid
         run: |
-          sudo npm install -g @mermaid-js/[email protected]
+          sudo npm install -g @mermaid-js/[email protected]
+          npx puppeteer browsers install chrome-headless-shell
 
       - name: Install asciidoctor
         run: |
@@ -75,32 +76,32 @@ jobs:
         run: |
           pip install mypy black
 
-      - name: Restore CPM cache
-        env:
-          cache-name: cpm-cache-0
-        id: cpm-cache-restore
-        uses: actions/cache/restore@6849a6489940f00c2f30c0fb92c6274307ccb58a # v4.1.2
-        with:
-          path: ~/cpm-cache
-          key: ${{runner.os}}-${{env.cache-name}}-${{ hashFiles('**/CMakeLists.txt', 'cmake/**') }}
-          restore-keys: |
-            ${{runner.os}}-${{env.cache-name}}-
-
       - name: Configure cmake for lib
         env:
           CC: "/usr/lib/llvm-${{env.TARGET_LLVM_VERSION}}/bin/clang"
           CXX: "/usr/lib/llvm-${{env.TARGET_LLVM_VERSION}}/bin/clang++"
           PR_TARGET_BRANCH: ${{ steps.target_branch.outputs.branch }}
         working-directory: ${{github.workspace}}/test/library
-        run: cmake -Bbuild -DCPM_SOURCE_CACHE=~/cpm-cache
+        run: cmake -Bbuild
 
       - name: Check lib quality
         working-directory: ${{github.workspace}}/test/library
         run: cmake --build build -t ci-quality
 
       - name: Build lib docs
         working-directory: ${{github.workspace}}/test/library
-        run: cmake --build build -t docs
+        run: test $(cmake --build build -v -t docs | grep -c ERROR) == 0
+
+      - name: Restore CPM cache
+        env:
+          cache-name: cpm-cache-0
+        id: cpm-cache-restore
+        uses: actions/cache/restore@6849a6489940f00c2f30c0fb92c6274307ccb58a # v4.1.2
+        with:
+          path: ~/cpm-cache
+          key: ${{runner.os}}-${{env.cache-name}}-${{ hashFiles('**/CMakeLists.txt', 'cmake/**') }}
+          restore-keys: |
+            ${{runner.os}}-${{env.cache-name}}-
 
       - name: Configure cmake for app
         env:

ci/.github/workflows/asciidoctor-ghpages.yml

@@ -40,7 +40,8 @@ jobs:
           node-version: 20
       - name: Install Mermaid
         run: |
-          sudo npm install -g @mermaid-js/[email protected]
+          sudo npm install -g @mermaid-js/[email protected]
+          npx puppeteer browsers install chrome-headless-shell
       - name: Install asciidoctor
         run: |
           sudo apt update

cmake/main.cmake

@@ -28,6 +28,10 @@ option(INFRA_PROVIDE_PRESETS "Provide cmake presets and toolchains" ON)
 option(INFRA_PROVIDE_MULL "Provide mull.yml file" ON)
 option(INFRA_PROVIDE_PYTEST_REQS
        "Provide pip requirements.txt for python tests" ON)
+option(
+    INFRA_PROVIDE_PUPPETEER_CONFIG
+    "Provide puppeteer_config.json for generating mermaid diagrams in documentation"
+    ON)
 option(INFRA_PROVIDE_GITIGNORE "Add provided things to .gitignore" ON)
 option(INFRA_USE_SYMLINKS "Use symlinks to provide common files" ON)
 
@@ -38,6 +42,8 @@ if(${PROJECT_SOURCE_DIR}/cmake STREQUAL CMAKE_CURRENT_LIST_DIR)
     set(INFRA_PROVIDE_CMAKE_FORMAT OFF)
     set(INFRA_PROVIDE_PRESETS OFF)
     set(INFRA_PROVIDE_MULL OFF)
+    set(INFRA_PROVIDE_PYTEST_REQS OFF)
+    set(INFRA_PROVIDE_PUPPETEER_CONFIG OFF)
     set(INFRA_PROVIDE_GITIGNORE OFF)
 endif()
 

cmake/setup.cmake

@@ -46,6 +46,11 @@ function(make_gitignore)
                 list(APPEND GITIGNORE_CONTENTS "requirements.txt")
             endif()
         endif()
+        if(INFRA_PROVIDE_PUPPETEER_CONFIG)
+            if(NOT EXISTS "${CMAKE_SOURCE_DIR}/docs/puppeteer_config.json")
+                list(APPEND GITIGNORE_CONTENTS "docs/puppeteer_config.json")
+            endif()
+        endif()
     endif()
 
     string(REPLACE ";" "\n" GITIGNORE_CONTENTS "${GITIGNORE_CONTENTS}")
@@ -61,6 +66,10 @@ function(make_gitignore)
 endfunction()
 
 function(put_in_project_dir FILENAME)
+    get_filename_component(DIRNAME ${FILENAME} DIRECTORY)
+    execute_process(COMMAND ${CMAKE_COMMAND} -E make_directory
+                            "${CMAKE_SOURCE_DIR}/${DIRNAME}")
+
     if(INFRA_USE_SYMLINKS)
         set(put_command "create_symlink")
     else()
@@ -120,6 +129,9 @@ if(PROJECT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
     if(INFRA_PROVIDE_PYTEST_REQS)
         put_in_project_dir("requirements.txt")
     endif()
+    if(INFRA_PROVIDE_PUPPETEER_CONFIG)
+        put_in_project_dir("docs/puppeteer_config.json")
+    endif()
 
     if(INFRA_PROVIDE_GITHUB_WORKFLOWS)
         execute_process(COMMAND ${CMAKE_COMMAND} -E make_directory

docs/index.adoc

@@ -5,6 +5,7 @@
 :rouge-style: base16.solarized
 :source-language: c++
 :toc: left
+:mermaid-puppeteer-config: puppeteer_config.json
 
 include::intro.adoc[]
 include::options.adoc[]

docs/puppeteer_config.json

@@ -0,0 +1,3 @@
+{
+  "args": ["--no-sandbox"]
+}

test/application/clean.sh

@@ -9,6 +9,8 @@ rm -f mull.yml
 rm -f .gitignore
 rm -f CMakePresets.json
 rm -f toolchains
+rm -f requirements.txt
 
+rm -rf docs
 rm -rf build
 rm -rf .github

test/library/clean.sh

@@ -9,6 +9,8 @@ rm -f mull.yml
 rm -f .gitignore
 rm -f CMakePresets.json
 rm -f toolchains
+rm -f requirements.txt
+rm -f docs/puppeteer_config.json
 
 rm -rf build
 rm -rf .github

test/library/docs/index.adoc

@@ -6,6 +6,7 @@ Ben Deane <[email protected]>
 :rouge-style: base16.solarized
 :source-language: c++
 :toc: left
+:mermaid-puppeteer-config: puppeteer_config.json
 
 == Introduction