docs: Update to allow better regal docs generation (#1578)

To be consumed by

https://github.com/StyraInc/docs/pull/424

Signed-off-by: Charlie Egan <charlie@styra.com>

Author: Charlie Egan

README.md

@@ -91,6 +91,7 @@ job contains "pr" if {
 
 	# format
 	fmt_all
+	write_readme
 	golangcilintfix
 
 	# verify
@@ -139,6 +140,14 @@ build(false) if {
 	run("go build -tags=regal_standalone")
 } else := true
 
+# METADATA
+# title: check_readme
+# description: Verify that the rules table in the README is up-to-date
+job contains "check_readme" if {
+	build(true)
+	check_readme
+}
+
 # any binary is good enough when calling `build(false)`, it doesn't need to be
 # built freshly
 binary_present if {
@@ -161,14 +170,14 @@ e2e if {
 lint if {
 	run("opa check --strict --capabilities build/capabilities.json bundle")
 	run("./regal lint --format pretty bundle")
-	run("npx --prefix build markdownlint --config docs/.markdownlint.yaml --ignore docs/CODE_OF_CONDUCT.md README.md docs/")
+	run("npx --prefix build markdownlint --config docs/.markdownlint.yaml --ignore docs/CODE_OF_CONDUCT.md --ignore README.md docs/")
 	run("npx --prefix build dprint --config build/dprint.json check")
 }
 
 lint_ci if {
 	run("opa check --strict --capabilities build/capabilities.json bundle")
 	run_quiet("./regal lint --format github bundle")
-	run("npx --prefix build markdownlint --config docs/.markdownlint.yaml --ignore docs/CODE_OF_CONDUCT.md README.md docs/")
+	run("npx --prefix build markdownlint --config docs/.markdownlint.yaml --ignore docs/CODE_OF_CONDUCT.md --ignore README.md docs/")
 	run("npx --prefix build dprint --config build/dprint.json check")
 }
 
@@ -293,6 +302,14 @@ fetch_eopa_caps if {
 	}
 }
 
+check_readme if {
+	run("./build/update-readme.sh check")
+}
+
+write_readme if {
+	run("./build/update-readme.sh write")
+}
+
 fmt_all if {
 	opafmt
 }

build/do.rq

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+
+README_SECTIONS_DIR="./docs/readme-sections"
+README_PATH="./README.md"
+MANIFEST="$README_SECTIONS_DIR/github-manifest"
+
+if [[ $# -ne 1 ]]; then
+  echo "Usage: $0 {check|write}"
+  exit 1
+fi
+
+MODE="$1"
+
+# Create a temporary file to hold the new content
+tmpfile=$(mktemp)
+
+# Build new content into tmpfile
+while IFS= read -r file; do
+  section_path="$README_SECTIONS_DIR/$file"
+
+  if [[ -f "$section_path" ]]; then
+    cat "$section_path" >> "$tmpfile"
+    echo -e "\n" >> "$tmpfile"
+  else
+    echo "Warning: Section file not found: $section_path" >&2
+  fi
+done < "$MANIFEST"
+
+if [[ "$MODE" == "check" ]]; then
+  if ! cmp -s "$tmpfile" "$README_PATH"; then
+    echo "README.md is out of date. Please run '$0 write' to update it."
+    rm "$tmpfile"
+    exit 1
+  else
+    echo "README.md is up to date."
+  fi
+elif [[ "$MODE" == "write" ]]; then
+  mv "$tmpfile" "$README_PATH"
+  echo "README.md has been updated."
+else
+  echo "Unknown mode: $MODE"
+  echo "Usage: $0 {check|write}"
+  rm "$tmpfile"
+  exit 1
+fi

build/update-readme.sh

@@ -0,0 +1 @@
+sidebar_position: 13

docs/adopters.md.yaml

@@ -0,0 +1 @@
+sidebar_position: 4

docs/architecture.md.yaml

@@ -0,0 +1,2 @@
+sidebar_label: CI/CD
+sidebar_position: 8

docs/cicd.md.yaml

@@ -0,0 +1 @@
+sidebar_position: 5

docs/custom-rules.md.yaml

@@ -0,0 +1 @@
+sidebar_position: 10

docs/debug-adapter.md.yaml

@@ -1,4 +1,4 @@
-# Editor support
+# Editor Support
 
 ## Visual Studio Code
 

docs/editor-support.md

@@ -0,0 +1 @@
+sidebar_position: 7