Added reference doc workflow

.docs-test.toml

@@ -53,6 +53,18 @@ consoleErrors = [
   # "invalid_request" pageerror with no stack. Not fixable without a live
   # backend — suppress until those scripts are refactored to not throw on init.
   "invalid_request",
+  # Qualified's chat widget posts to its own sentry proxy on every page load, so
+  # a site-wide crawl fires one request per page within a few seconds and trips
+  # that endpoint's rate limit. Whichever pages land after the limit then fail
+  # with a 429, which makes the failing set shift run to run (48/16/17/0 failures
+  # across four runs of the same suite) and reads as a content regression when it
+  # is a property of the crawl's request rate. Scoped to the status AND the host
+  # so a genuine 429 from our own origin still fails the check.
+  #
+  # TEMPORARY: this suppresses the error but the request still fires. The real
+  # fix is to block third-party hosts at the network layer during the crawl —
+  # see solo-io/docs-theme-extras#39. Remove this entry once that lands.
+  "status of 429 .*app\\.qualified\\.com",
   # NOTE: agr previously allowlisted two Hextra main.min.js null-dereferences
   # (reading 'removeAttribute' / 'addEventListener') that fired on pages with no
   # real sidebar (e.g. the /docs/ landing page), where main.js can't find the
@@ -64,3 +76,28 @@ consoleErrors = [
   # (and in the static "Hextra hamburger toggle target" guard in docs-theme-extras).
   # Ported from the same fix in agw-oss.
 ]
+
+# Builds this source tree is rendered under, for the gateAxisCollision lint.
+#
+# `conditional-text` gates on two axes — the build condition and the page's
+# section segment — through one token namespace, so a token naming a section on
+# one axis and a product on the other is true twice and both sides of an
+# intended either/or render.
+#
+# THIS SITE'S OWN BUILD CANNOT FIRE A GATE AT ALL. It registers no
+# `params.sections`, and in `url` mode utils/page-context.html assigns a
+# condition only when the path carries a section AND a version — with no
+# sections registered that never happens, so the condition is always "" and
+# conditional-text emits nothing. Consistent with the corpus: it uses no gates
+# today.
+#
+# The docs hub ships an agentregistry product (buildCondition "agentregistry"),
+# but its module import of this repo is still commented out, so nothing here is
+# rendered under that condition yet. The entry below is staged for when it is:
+# once the import is enabled, a gate written here starts resolving downstream
+# while staying inert upstream, which is precisely the asymmetry this lint
+# catches.
+[[gateAxes]]
+name      = "docs-hub / agentregistry"
+condition = "agentregistry"
+sections  = []

.github/workflows/reference-docs.yml

@@ -1,30 +1,129 @@
-name: Generate CLI Reference
+# Regenerates the reference docs from the agentregistry product repo and opens a
+# PR with the result. Three sources, one PR:
+#
+#   arctl CLI    generate-arctl-ref.py builds a throwaway Go module that imports
+#                arctl's exported command tree through a `replace` directive,
+#                runs cobra's doc generator, and rewrites the output into Hugo
+#                pages. cobra/doc's markdown dependencies stay out of the
+#                product's go.mod because they live in that throwaway module.
+#   Helm values  generate-helm-ref.py runs the helm-docs pinned in the product
+#                repo's tools module, with our own values-only template.
+#   REST API     generate-api-ref.py copies openapi.yaml into assets/ so the
+#                spec is served same-origin.
+#
+# agentregistry needs no changes to support any of this.
+#
+# agentregistry docs are unversioned — one flat content tree — so unlike the
+# equivalent agentgateway workflow there is no version matrix here.
+name: Reference docs
 
 on:
-  push:
-    branches: [ main ]
-    paths:
-      - 'internal/cli/**' # Only run if CLI code changes
+  schedule:
+    # Nightly at 06:00 UTC, so published docs don't drift from merged CLI changes.
+    - cron: '0 6 * * *'
+  workflow_dispatch:
+    inputs:
+      agentregistry_ref:
+        description: 'agentregistry ref to generate from (branch, tag, or SHA)'
+        required: false
+        default: 'main'
+
+# Queue overlapping runs (nightly cron plus a manual dispatch) rather than
+# letting them force-push the same PR branch concurrently.
+concurrency:
+  group: reference-docs
+  cancel-in-progress: false
+
+# create-pull-request pushes a branch and opens a PR, so the token needs write
+# on both. Without this the token is read-only and the push fails with a 403.
+#
+# The PR is authored by github-actions[bot], which requires the repo setting
+# "Allow GitHub Actions to create and approve pull requests". A consequence is
+# that pull_request workflows (framework-tests, links) are queued on the
+# generated PR but held as "action_required" — click "Approve and run" on the
+# PR's checks to execute them.
+permissions:
+  contents: write
+  pull-requests: write
 
 jobs:
-  docs:
+  reference:
+    name: Generate reference docs
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
+      - name: Check out the website
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
-          fetch-depth: 0
+          path: website
+
+      - name: Check out agentregistry
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          repository: agentregistry-dev/agentregistry
+          ref: ${{ inputs.agentregistry_ref || 'main' }}
+          path: agentregistry
+
+      - name: Record the agentregistry revision
+        id: source
+        working-directory: agentregistry
+        run: echo "sha=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT"
 
       - name: Set up Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@4b73464bb391d4059bd26b0524d20df3927bd417 # v6.3.0
         with:
-          go-version: '1.22' # Match your project version
+          go-version-file: agentregistry/go.mod
+          cache: false
 
-      - name: Generate Markdown Docs
-        run: go run scripts/docgen.go
+      # helm-docs is invoked through `go tool -modfile=tools/go.mod`, and
+      # `make charts-generate` needs envsubst (preinstalled on ubuntu runners).
+      - name: Generate the reference docs
+        env:
+          WEBSITE_DIR: website
+          AGENTREGISTRY_DIR: agentregistry
+        run: |
+          python3 website/scripts/generate-arctl-ref.py
+          python3 website/scripts/generate-helm-ref.py
+          python3 website/scripts/generate-api-ref.py
 
-      - name: Commit and Push changes
-        uses: stefanzweifel/git-auto-commit-action@v5
+      - name: Open a PR
+        id: pr
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
         with:
-          commit_message: "docs: auto-generate CLI reference"
-          file_pattern: 'content/docs/reference/cli/*.md'
+          path: website
+          base: main
+          branch: ref-docs-arctl
+          delete-branch: true
+          title: '[Automated] Update the reference docs'
+          commit-message: |
+            docs: regenerate the CLI, Helm, and API reference from agentregistry ${{ steps.source.outputs.sha }}
+
+            Signed-off-by: GitHub Action <action@github.com>
+          committer: GitHub Action <action@github.com>
+          body: |
+            Regenerated the reference docs from
+            [`${{ steps.source.outputs.sha }}`](https://github.com/agentregistry-dev/agentregistry/commit/${{ steps.source.outputs.sha }}).
+
+            | Page | Generated from |
+            |---|---|
+            | `content/docs/reference/cli/` | the arctl cobra command definitions |
+            | `content/docs/reference/helm.md` | the chart's `values.yaml`, via helm-docs |
+            | `content/docs/reference/api.md` + `assets/ar-docs/openapi.yaml` | `openapi.yaml` |
+
+            All of these are generated, front matter included. Edit the sources
+            upstream rather than these files — the next run overwrites anything
+            changed by hand.
+
+            Opened automatically by the [Reference docs workflow](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}).
+          labels: |
+            documentation
+            automated pr
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Report the result
+        run: |
+          if [ -n "${{ steps.pr.outputs.pull-request-url }}" ]; then
+            echo "PR: ${{ steps.pr.outputs.pull-request-url }}"
+          else
+            echo "The reference is already up to date; no PR opened."
+          fi

.gitignore

@@ -34,3 +34,4 @@ yarn.lock
 
 # Backup directory
 nextjs-backup/
+scripts/__pycache__/