docs: move public docs generation to local workflow

.github/workflows/generate-docs.yml

@@ -1,4 +1,4 @@
-name: Generate documentation
+name: Validate committed public docs
 
 on:
   push:
@@ -16,53 +16,16 @@ on:
       - "docs/public/**"
       - "site/**"
   workflow_dispatch:
-    inputs:
-      commit_generated_docs:
-        description: "Commit generated docs back to the branch"
-        required: false
-        default: "false"
-        type: choice
-        options: ["false", "true"]
 
 permissions:
-  contents: write
+  contents: read
 
 jobs:
-  generate-docs:
+  validate-public-docs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-        with:
+      - name: Ensure committed docs/public exists
-          fetch-depth: 0
-      - name: Install tooling
         run: |
-          sudo apt-get update
+          test -d docs/public
-          sudo apt-get install -y graphviz jq python3 python3-pip
+          test -n "$(find docs/public -mindepth 1 -print -quit)"
-          if ! docker compose version >/dev/null 2>&1; then
-            sudo apt-get install -y docker-compose-v2 || sudo apt-get install -y docker-compose || true
-          fi
-          if ! docker compose version >/dev/null 2>&1; then
-            echo "docker compose CLI is unavailable on this runner" >&2
-            exit 1
-          fi
-          python3 -m pip install --user pyyaml jinja2
-      - name: Generate documentation
-        run: |
-          chmod +x scripts/docs/*.sh
-          scripts/docs/generate-all.sh
-      - name: Upload generated documentation
-        uses: actions/upload-artifact@v4
-        with:
-          name: generated-documentation
-          path: |
-            docs/generated
-            docs/diagrams
-            docs/public
-      - name: Commit generated docs
-        if: >
-          github.event_name == 'push' ||
-          (github.event_name == 'workflow_dispatch' && inputs.commit_generated_docs == 'true')
-        uses: stefanzweifel/git-auto-commit-action@v5
-        with:
-          commit_message: "docs: regenerate environment documentation"
-          file_pattern: docs/generated docs/diagrams docs/public

.github/workflows/publish-docs.yml

@@ -23,30 +23,18 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Install tooling
+      - name: Ensure committed docs/public exists
         run: |
-          sudo apt-get update
+          test -d docs/public
-          sudo apt-get install -y graphviz jq python3 python3-pip
+          test -n "$(find docs/public -mindepth 1 -print -quit)"
 
-          if ! docker compose version >/dev/null 2>&1; then
+      - name: Install MkDocs
-            sudo apt-get install -y docker-compose-v2 || sudo apt-get install -y docker-compose || true
-          fi
-
-          if ! docker compose version >/dev/null 2>&1; then
-            echo "docker compose CLI is unavailable on this runner" >&2
-            exit 1
-          fi
-
-          python3 -m pip install --user mkdocs pyyaml jinja2
-
-      - name: Generate documentation
         run: |
-          chmod +x scripts/docs/*.sh
+          python3 -m pip install --user mkdocs
-          scripts/docs/generate-all.sh
 
-      - name: Build MkDocs site
+      - name: Build public MkDocs site
         run: |
-          python3 -m mkdocs build --strict
+          python3 -m mkdocs build --strict -f mkdocs-public.yml -d site-public
 
       - name: Configure GitHub Pages
         uses: actions/configure-pages@v5
@@ -54,7 +42,7 @@ jobs:
       - name: Upload GitHub Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: site
+          path: site-public
 
   deploy:
     runs-on: ubuntu-latest

README.md

@@ -120,6 +120,37 @@ flowchart TB
 
 For request-flow and network detail, see [docs/architecture.md](docs/architecture.md).
 
+## Public docs publication workflow
+
+Public docs are generated on the Docker host and committed to this repository. GitHub Actions only publishes committed content from `docs/public`.
+
+1. Generate public docs locally from the repository root:
+
+   ```bash
+   ./scripts/generate-public-docs.sh
+   ```
+
+2. Inspect the generated changes:
+
+   ```bash
+   git diff -- docs/public docs/generated docs/diagrams
+   ```
+
+3. Commit the generated public docs (and any supporting generated files you intend to version):
+
+   ```bash
+   git add docs/public docs/generated docs/diagrams
+   git commit -m "docs: regenerate public docs"
+   ```
+
+4. Push your branch:
+
+   ```bash
+   git push
+   ```
+
+Only files under `docs/public` are published by GitHub Pages. Internal/generated documentation is not published unless it is deliberately copied/sanitized into `docs/public`.
+
 ### Regenerating architecture docs (Prometheus + Dynu DNS)
 
 ```bash

mkdocs-public.yml

@@ -0,0 +1,13 @@
+site_name: Public Infrastructure Documentation
+site_description: Sanitized public documentation generated and committed from the docker host
+repo_url: https://github.com/beatz174-bit/docker
+docs_dir: docs/public
+
+nav:
+  - Home: index.md
+  - Compose Inventory: compose-inventory.md
+  - Traefik Routes: traefik-routes.md
+  - Prometheus Rules: prometheus-rules.md
+
+theme:
+  name: mkdocs

scripts/docs/render-compose-config.sh

@@ -9,20 +9,13 @@ if [ "${#COMPOSE_FILES[@]}" -eq 0 ]; then
   exit 1
 fi
 printf '%s\n' "${COMPOSE_FILES[@]}" > docs/generated/compose-files.txt
-ARGS=()
+
-for file in "${COMPOSE_FILES[@]}"; do ARGS+=("-f" "$file"); done
+if [ ! -x ./services-up.sh ]; then
-ENV_FILE=""
+  echo "services-up.sh is missing or not executable" >&2
-if [ -f default-environment.env ]; then
-  ENV_FILE="default-environment.env"
-else
-  ENV_FILE="scripts/docs/ci-default.env"
-fi
-if [ ! -f "$ENV_FILE" ]; then
-  echo "Environment file not found: $ENV_FILE" >&2
   exit 1
 fi
 
-docker compose -p core --env-file "$ENV_FILE" --profile all "${ARGS[@]}" config > docs/generated/docker-compose.resolved.yml
+./services-up.sh --profile all config > docs/generated/docker-compose.resolved.yml
 
 service_count="$(
   python3 - <<'PY'

scripts/generate-public-docs.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$ROOT"
+
+mkdir -p docs/generated docs/diagrams docs/public
+
+scripts/docs/generate-all.sh
+
+if [ ! -d docs/public ] || [ -z "$(find docs/public -mindepth 1 -print -quit)" ]; then
+  echo "ERROR: docs/public is missing or empty after generation." >&2
+  exit 1
+fi
+
+echo "Public docs generated in docs/public. Review changes before commit."