diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS deleted file mode 100644 index 8ffb4b4..0000000 --- a/.github/CODEOWNERS +++ /dev/null @@ -1 +0,0 @@ -* @jzone3 \ No newline at end of file diff --git a/.github/workflows/docs-validation.yml b/.github/workflows/docs-validation.yml new file mode 100644 index 0000000..6f6cb98 --- /dev/null +++ b/.github/workflows/docs-validation.yml @@ -0,0 +1,37 @@ +name: Docs validation + +on: + pull_request: + branches: + - master + workflow_dispatch: + +permissions: + contents: read + +jobs: + validate-docs: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: 22 + + - name: Install Mintlify CLI + run: npm install -g mint + + - name: Validate JSON + run: | + jq empty docs.json + jq empty openapi.json + + - name: Check broken links + run: mint broken-links + + - name: Validate Mintlify docs + run: mint validate diff --git a/.github/workflows/update-docs.yml b/.github/workflows/update-docs.yml deleted file mode 100644 index d76f61a..0000000 --- a/.github/workflows/update-docs.yml +++ /dev/null @@ -1,282 +0,0 @@ -name: Update Documentation - -on: - schedule: - - cron: '0 9 * * *' # Runs daily at 09:00 UTC - workflow_dispatch: # Allows manual triggering - -permissions: - contents: write - pull-requests: write - issues: write - id-token: write - actions: read - -concurrency: - group: update-documentation - cancel-in-progress: false - -jobs: - update-docs: - runs-on: ubuntu-latest - timeout-minutes: 30 - env: - GH_TOKEN: ${{ github.token }} - - steps: - - name: Checkout docs repository - uses: actions/checkout@v4 - with: - token: ${{ github.token }} - fetch-depth: 0 # Get full history for better git operations - - - name: Compute lookback window - run: | - echo "SINCE=$(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ)" >> $GITHUB_ENV - echo "TODAY=$(date -u +%F)" >> $GITHUB_ENV - echo "Looking for commits since: $(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ)" - - - name: Checkout prompt-layer-front-end - uses: actions/checkout@v4 - with: - repository: MagnivOrg/prompt-layer-front-end - token: ${{ secrets.GH_READ_TOKEN }} - path: repos/prompt-layer-front-end - fetch-depth: 0 # Get full history for better git log - - - name: Checkout prompt-layer-api - uses: actions/checkout@v4 - with: - repository: MagnivOrg/prompt-layer-api - token: ${{ secrets.GH_READ_TOKEN }} - path: repos/prompt-layer-api - fetch-depth: 0 - - - name: Checkout prompt-layer-python-sdk - uses: actions/checkout@v4 - with: - repository: MagnivOrg/prompt-layer-library - token: ${{ secrets.GH_READ_TOKEN }} - path: repos/prompt-layer-library - fetch-depth: 0 - - - name: Checkout prompt-layer-javascript-sdk - uses: actions/checkout@v4 - with: - repository: MagnivOrg/prompt-layer-js - token: ${{ secrets.GH_READ_TOKEN }} - path: repos/prompt-layer-js - fetch-depth: 0 - - - name: Configure git identity - run: | - git config --global user.name "github-actions[bot]" - git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com" - - - name: Verify repository checkouts - run: | - echo "Current directory: $(pwd)" - echo "Directory contents:" - ls -la - echo "Repos directory contents:" - ls -la repos/ || echo "No repos directory found" - - - name: Ensure we're in docs root directory - run: | - echo "Setting working directory to docs root" - cd ${{ github.workspace }} - pwd - echo "Verifying repos are accessible:" - ls -la repos/ - - - name: Verify Anthropic API key is configured - id: verify-api-key - run: | - if [ -z "${{ secrets.ANTHROPIC_API_KEY }}" ]; then - echo "::error::ANTHROPIC_API_KEY secret is not set in repository secrets!" - exit 1 - fi - - - name: Test Anthropic API key and check credits - id: test-api-key - continue-on-error: true - run: | - API_KEY="${{ secrets.ANTHROPIC_API_KEY }}" - RESPONSE=$(curl -s -w "\n%{http_code}" \ - -X POST https://api.anthropic.com/v1/messages \ - -H "x-api-key: $API_KEY" \ - -H "anthropic-version: 2023-06-01" \ - -H "content-type: application/json" \ - -d '{"model": "claude-3-5-sonnet-20241022", "max_tokens": 10, "messages": [{"role": "user", "content": "Hi"}]}' 2>&1) - - HTTP_CODE=$(echo "$RESPONSE" | tail -n1) - echo "API response: $HTTP_CODE" - - case "$HTTP_CODE" in - 200) - echo "API key valid" - echo "api_status=valid" >> $GITHUB_OUTPUT - ;; - 401) - echo "::error::API key authentication failed (401 Unauthorized). Check your API key at https://console.anthropic.com/" - echo "api_status=invalid" >> $GITHUB_OUTPUT - exit 1 - ;; - 402) - echo "::error::Insufficient credits/quota (402 Payment Required). Add credits at https://console.anthropic.com/" - echo "api_status=no_credits" >> $GITHUB_OUTPUT - exit 1 - ;; - 429) - echo "::warning::Rate limit exceeded (429). Will retry." - echo "api_status=rate_limited" >> $GITHUB_OUTPUT - ;; - *) - echo "::warning::Unexpected API response: $HTTP_CODE" - echo "api_status=unknown" >> $GITHUB_OUTPUT - ;; - esac - - - - name: Run Claude Code to update documentation - id: claude-code - if: steps.test-api-key.outcome == 'success' || (steps.test-api-key.outcome == 'failure' && steps.test-api-key.outputs.api_status != 'invalid' && steps.test-api-key.outputs.api_status != 'no_credits') - continue-on-error: true - working-directory: ${{ github.workspace }} - uses: anthropics/claude-code-action@v1 - with: - anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} - show_full_output: true - additional_permissions: | - Bash(git -C repos/* log:*) - Bash(git -C repos/* show:*) - Bash(git -C repos/* diff:*) - prompt: | - Read the CLAUDE.md file in this repository for documentation update policy and guidelines. - - ## Context - - Time window: commits since "${{ env.SINCE }}" (UTC) until now - - Today's date: ${{ env.TODAY }} - - Repositories checked out in local paths: - - repos/prompt-layer-front-end - - repos/prompt-layer-api - - repos/prompt-layer-library - - repos/prompt-layer-js - - ## Task - 1. Read CLAUDE.md to understand the documentation policy - 2. For each repository, examine commits since "${{ env.SINCE }}" using git log: - - Use: `git -C repos/[repo-name] log --since="${{ env.SINCE }}" --no-merges --oneline --name-status` - 3. For commits that might be user-facing, examine the diff: `git -C repos/[repo-name] show [commit-hash]` - 4. Apply the Decision Framework from CLAUDE.md strictly to identify user-facing changes - 5. Update appropriate documentation files if any changes qualify - 6. If no user-facing changes are found, make no edits - - - name: Handle Claude Code errors - if: steps.claude-code.outcome == 'failure' - run: | - echo "::error::Claude Code action failed!" - exit 1 - - - name: Check for changes - id: check-changes - if: steps.claude-code.outcome == 'success' - working-directory: ${{ github.workspace }} - run: | - if [[ -n $(git status --porcelain) ]]; then - echo "changes=true" >> $GITHUB_OUTPUT - git status --porcelain - else - echo "changes=false" >> $GITHUB_OUTPUT - fi - - - name: Create or update PR - if: steps.check-changes.outputs.changes == 'true' - working-directory: ${{ github.workspace }} - env: - GH_TOKEN: ${{ github.token }} - run: | - BRANCH="docs/auto-update-${{ env.TODAY }}" - - CURRENT_BRANCH=$(git branch --show-current) - if [ -z "$CURRENT_BRANCH" ] || [ "$CURRENT_BRANCH" = "HEAD" ]; then - git checkout main 2>/dev/null || git checkout master 2>/dev/null - fi - - if git ls-remote --heads origin "$BRANCH" | grep -q "$BRANCH"; then - git fetch origin "$BRANCH" - git checkout "$BRANCH" || git checkout -b "$BRANCH" - git pull origin "$BRANCH" - else - git checkout -b "$BRANCH" - fi - - git add . - if git diff --staged --quiet; then - exit 0 - fi - - git commit -m "docs: automated documentation update for ${{ env.TODAY }} - - This automated update includes user-facing changes from: - - prompt-layer-front-end - - prompt-layer-api - - prompt-layer-library (Python SDK) - - prompt-layer-js (JavaScript SDK) - - Time window: ${{ env.SINCE }} to now - Generated by GitHub Actions bot using Claude Code" - - git push -u origin "$BRANCH" - - DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@' 2>/dev/null || echo "master") - if ! git show-ref --verify --quiet refs/remotes/origin/"$DEFAULT_BRANCH"; then - if git show-ref --verify --quiet refs/remotes/origin/main; then - DEFAULT_BRANCH="main" - else - DEFAULT_BRANCH="master" - fi - fi - - PR_NUMBER=$(gh pr list --head "$BRANCH" --state open --json number --jq '.[0].number' 2>/dev/null || echo "") - - if [ -z "$PR_NUMBER" ]; then - gh pr create \ - --title "docs: automated update - ${{ env.TODAY }}" \ - --body "## Automated Documentation Update - - This PR contains automated documentation updates based on user-facing changes from the last 24 hours. - - ### Time Window - - Since: ${{ env.SINCE }} - - Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ) - - ### Repositories Scanned - - \`prompt-layer-front-end\` (Frontend) - - \`prompt-layer-api\` (Backend API) - - \`prompt-layer-library\` (Python SDK) - - \`prompt-layer-js\` (JavaScript SDK) - - ### What Gets Documented - Per our documentation policy (CLAUDE.md): - - ✅ NEW features and capabilities - - ✅ Public API/SDK changes - - ✅ Breaking changes and deprecations - - ✅ New integrations or model support - - ❌ UI/UX improvements - - ❌ Bug fixes and performance enhancements - - ❌ Internal refactoring - - ### Review Checklist - - [ ] New features are properly documented - - [ ] API/SDK changes include examples - - [ ] Breaking changes are clearly marked - - [ ] Documentation follows our standards - - [ ] No unrelated files were modified - - Generated by Claude Code Documentation Bot" \ - --base "$DEFAULT_BRANCH" \ - --head "$BRANCH" - else - gh pr comment "$PR_NUMBER" --body "📝 Documentation updated with latest changes from ${{ env.TODAY }}" - fi \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 3898c91..b10d282 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -80,12 +80,3 @@ Before approving, check that: - `openapi` frontmatter exactly matches `openapi.json`. - OpenAPI contains the real API contract and examples. - Copy is concise, useful, and public-facing. - -For nav, frontmatter, OpenAPI, or link changes, run: - -```sh -jq empty docs.json -jq empty openapi.json -mint broken-links -mint validate -``` diff --git a/DOCS_UPDATER_SETUP_TODO.md b/DOCS_UPDATER_SETUP_TODO.md deleted file mode 100644 index 417f001..0000000 --- a/DOCS_UPDATER_SETUP_TODO.md +++ /dev/null @@ -1,120 +0,0 @@ -# Documentation Updater Setup - TODO - -## ✅ Completed Steps -- [x] Workflow file deployed to `.github/workflows/update-docs.yml` -- [x] CLAUDE.md policy file copied to docs repository root - -## 📋 Remaining Setup Steps - -### 1. Install Claude Code GitHub App -Run this command in Claude Code (in a new session): -```bash -/install-github-app -``` -This will open a browser to authorize the Claude Code GitHub integration. - -### 2. Create Personal Access Token (PAT) - -1. **Go to:** https://github.com/settings/tokens/new - -2. **Configure the token:** - - **Token name:** `Docs Updater Read Token` - - **Expiration:** 90 days (or custom) - - **Repository access:** Select "Selected repositories" and add: - - `MagnivOrg/prompt-layer-front-end` - - `MagnivOrg/prompt-layer-api` - - `MagnivOrg/prompt-layer-library` - - `MagnivOrg/prompt-layer-js` - - **Permissions:** - - Repository permissions → **Contents:** Read - - Repository permissions → **Metadata:** Read (automatically selected) - -3. **Click:** "Generate token" - -4. **IMPORTANT:** Copy the token immediately (starts with `ghp_`) - -### 3. Add Secrets to GitHub Repository - -1. **Go to:** https://github.com/MagnivOrg/prompt-layer-docs/settings/secrets/actions - -2. **Add Secret #1:** - - Click "New repository secret" - - **Name:** `GH_READ_TOKEN` - - **Value:** [Paste your Personal Access Token from step 2] - - Click "Add secret" - -3. **Add Secret #2:** - - Click "New repository secret" - - **Name:** `ANTHROPIC_API_KEY` - - **Value:** [Your Anthropic API key from console.anthropic.com] - - Click "Add secret" - -### 4. Commit and Push the Changes - -```bash -cd prompt-layer-docs -git add .github/workflows/update-docs.yml CLAUDE.md -git commit -m "feat: add automated documentation updater workflow - -- Daily GitHub Action to scan repos for user-facing changes -- Uses Claude Code to identify documentable changes -- Creates one PR per day with updates -- Excludes internal APIs and UI improvements" -git push origin main -``` - -### 5. Test the Workflow - -**Option A: Wait for the daily run** -- The workflow runs daily at 09:00 UTC - -**Option B: Trigger manually (recommended for first test)** -```bash -# From the prompt-layer-docs directory -gh workflow run update-docs.yml -gh run watch # Watch the execution -``` - -**Option C: Via GitHub UI** -1. Go to: https://github.com/MagnivOrg/prompt-layer-docs/actions -2. Click "Update Documentation" workflow -3. Click "Run workflow" → "Run workflow" - -### 6. Verify the Setup - -After the first run, check: -- [ ] Workflow completes successfully (green checkmark) -- [ ] If changes were found, a PR was created -- [ ] The PR contains only legitimate user-facing changes -- [ ] No internal API endpoints were documented - -## 🔒 Security Checklist - -- [ ] PAT has minimal permissions (read-only) -- [ ] PAT is set to expire (90 days recommended) -- [ ] Secrets are stored in GitHub, not in code -- [ ] Workflow file doesn't expose any secrets - -## 🚨 Troubleshooting - -### If the workflow fails: - -1. **Check Actions tab:** https://github.com/MagnivOrg/prompt-layer-docs/actions -2. **Common issues:** - - Missing secrets (GH_READ_TOKEN or ANTHROPIC_API_KEY) - - PAT doesn't have access to all 4 repos - - Claude Code GitHub app not installed - -### If no PR is created: -- This is normal if no user-facing changes were found -- Check the workflow logs to see what commits were analyzed - -### If wrong things are documented: -- Review the CLAUDE.md policy file -- Internal `/api/dashboard/v2/*` endpoints should be skipped -- UI improvements should be skipped - -## 📞 Support - -- **Claude Code issues:** https://github.com/anthropics/claude-code/issues -- **Workflow logs:** https://github.com/MagnivOrg/prompt-layer-docs/actions \ No newline at end of file