feat: add script to generate offline docs

Signed-off-by: Patrick Stephens <pat@fluent.do>

Author: patrick-stephens

.github/workflows/build-offline.yaml

@@ -0,0 +1,27 @@
+name: Build an offline version of the documentation
+on:
+  workflow_dispatch:
+
+jobs:
+    build:
+        name: Generate documentation and upload
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+        steps:
+            - uses: actions/checkout@v4
+
+            - run: scripts/generate-offline.sh
+              shell: bash
+
+            - name: Debug
+              if: always()
+              continue-on-error: true
+              run: ls -lR
+              shell: bash
+
+            - uses: actions/upload-artifacts@v4
+              with:
+                name: fluentdo-agent-documentation
+                path: *.tgz
+                if-no-files-found: error

.gitignore

@@ -1 +1,5 @@
 gha-creds*.json
+.cache
+site/
+*.tar*
+*.tgz

docs/security/cves.md

@@ -12,12 +12,12 @@ Please reach out to us at <info@fluent.do> directly for any specific concerns or
 
 ## OSS Version: 4.0.3
 
-- [Grype Markdown Report](agent/grype-4.0.3.md)
-- [Grype JSON Report](agent/grype-4.0.3.json)
-- [Syft JSON SBOM](agent/syft-4.0.3.json)
+- [Grype Markdown Report](oss/grype-4.0.3.md)
+- [Grype JSON Report](oss/grype-4.0.3.json)
+- [Syft JSON SBOM](oss/syft-4.0.3.json)
 
 ## OSS Version: 4.0.4
 
-- [Grype Markdown Report](agent/grype-4.0.4.md)
-- [Grype JSON Report](agent/grype-4.0.4.json)
-- [Syft JSON SBOM](agent/syft-4.0.4.json)
+- [Grype Markdown Report](oss/grype-4.0.4.md)
+- [Grype JSON Report](oss/grype-4.0.4.json)
+- [Syft JSON SBOM](oss/syft-4.0.4.json)

mkdocs.yml

@@ -12,6 +12,7 @@ plugins:
   - privacy
   - offline
   - search
+  - social
   - meta
 
 theme:

requirements.txt

@@ -2,3 +2,4 @@ mkdocs
 mkdocs-bootswatch
 mkdocs-minify-plugin
 mkdocs-material
+mkdocs-material[imaging]

scripts/generate-offline.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+set -eu
+
+# This does not work with a symlink to this script
+# SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+# See https://stackoverflow.com/a/246128/24637657
+SOURCE=${BASH_SOURCE[0]}
+while [ -L "$SOURCE" ]; do # resolve $SOURCE until the file is no longer a symlink
+  SCRIPT_DIR=$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )
+  SOURCE=$(readlink "$SOURCE")
+  # if $SOURCE was a relative symlink, we need to resolve it relative to the path where the symlink file was located
+  [[ $SOURCE != /* ]] && SOURCE=$SCRIPT_DIR/$SOURCE
+done
+SCRIPT_DIR=$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )
+REPO_ROOT=${REPO_ROOT:-$SCRIPT_DIR/..}
+GENERATED_DOC_DIR=${GENERATED_DOC_DIR:-$REPO_ROOT/site}
+OUTPUT_FILE=${OUTPUT_FILE:-$REPO_ROOT/fluentdo-agent-documentation.tgz}
+
+rm -rf "$GENERATED_DOC_DIR"
+
+echo "Generating documentation"
+${CONTAINER_RUNTIME:-docker} run --rm -t \
+  --volume /etc/passwd:/etc/passwd:ro --volume /etc/group:/etc/group:ro \
+  --user "$(id -u)":"$(id -g)" \
+  -v "${REPO_ROOT}":/docs squidfunk/mkdocs-material build
+
+if [[ ! -d "$GENERATED_DOC_DIR" ]]; then
+    echo "No documentation generated, missing 'site' directory"
+    exit 1
+fi
+
+echo "Creating $OUTPUT_FILE"
+rm -f "$OUTPUT_FILE"
+tar -czvf "$OUTPUT_FILE" -C "$GENERATED_DOC_DIR" .