Merge pull request #71 from beatz174-bit/codex/refactor-docs-pipeline-for-local-generation

docs: publish only committed public docs from GitHub Actions

.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:
-          fetch-depth: 0
-      - name: Install tooling
+      - name: Ensure committed docs/public exists
         run: |
-          sudo apt-get update
-          sudo apt-get install -y graphviz jq python3 python3-pip
-          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
+          test -d docs/public
+          test -n "$(find docs/public -mindepth 1 -print -quit)"

.github/workflows/publish-docs.yml

@@ -23,29 +23,20 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Install tooling
+      - name: Ensure committed docs/public exists
         run: |
-          sudo apt-get update
-          sudo apt-get install -y graphviz jq python3 python3-pip
+          test -d docs/public
+          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 mkdocs pyyaml jinja2
-
-      - name: Generate documentation
+      - name: Install MkDocs
         run: |
-          chmod +x scripts/docs/*.sh
-          scripts/docs/generate-all.sh
+          python3 -m pip install --user mkdocs
 
       - name: Build public MkDocs site
         run: |
+<<<<<<< codex/refactor-docs-pipeline-for-local-generation
+          python3 -m mkdocs build --strict -f mkdocs-public.yml -d site-public
+=======
           python3 -m mkdocs build -f mkdocs-public.yml --strict
 
       - name: Verify published content excludes internal/generated docs
@@ -59,6 +50,7 @@ jobs:
           test ! -e site-public/generated/compose-inventory/index.html
           test ! -e site-public/generated/prometheus-rules/index.html
           test ! -e site-public/docker/index.html
+>>>>>>> main
 
       - name: Configure GitHub Pages
         uses: actions/configure-pages@v5

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

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
-ENV_FILE=""
-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
+
+if [ ! -x ./services-up.sh ]; then
+  echo "services-up.sh is missing or not executable" >&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."