From e7fd52616d56352751476ebf9337c5d063ab6fc0 Mon Sep 17 00:00:00 2001 From: beatz174-bit Date: Wed, 13 May 2026 08:47:23 +1000 Subject: [PATCH] docs: move public docs generation to local workflow --- .github/workflows/generate-docs.yml | 49 ++++----------------------- .github/workflows/publish-docs.yml | 28 +++++---------- README.md | 31 +++++++++++++++++ mkdocs-public.yml | 13 +++++++ scripts/docs/render-compose-config.sh | 15 +++----- scripts/generate-public-docs.sh | 16 +++++++++ 6 files changed, 78 insertions(+), 74 deletions(-) create mode 100644 mkdocs-public.yml create mode 100755 scripts/generate-public-docs.sh diff --git a/.github/workflows/generate-docs.yml b/.github/workflows/generate-docs.yml index d63f726..242306a 100644 --- a/.github/workflows/generate-docs.yml +++ b/.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)" diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index 739d4a8..e8d0e0c 100644 --- a/.github/workflows/publish-docs.yml +++ b/.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 - 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 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 diff --git a/README.md b/README.md index 27791d1..e39b8fe 100644 --- a/README.md +++ b/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 diff --git a/mkdocs-public.yml b/mkdocs-public.yml new file mode 100644 index 0000000..3882e86 --- /dev/null +++ b/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 diff --git a/scripts/docs/render-compose-config.sh b/scripts/docs/render-compose-config.sh index ad9e847..0561fff 100755 --- a/scripts/docs/render-compose-config.sh +++ b/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' diff --git a/scripts/generate-public-docs.sh b/scripts/generate-public-docs.sh new file mode 100755 index 0000000..a4535ed --- /dev/null +++ b/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."