fix: update docgen templates and automate API reference generation

.github/workflows/generate-api-docs-community-contracts.yml

@@ -26,7 +26,10 @@ on:
         type: string
         default: 'commit'  # TODO: Update if using tags
 
-# TODO: Configure these environment variables for your contract
+permissions:
+  contents: write
+  pull-requests: write
+
 env:
   SOURCE_REPO: 'OpenZeppelin/openzeppelin-community-contracts'
   SOURCE_REPO_URL: 'https://github.com/OpenZeppelin/openzeppelin-community-contracts.git'
@@ -105,6 +108,11 @@ jobs:
             --branch "${{ inputs.tag_name }}" \
             --api-output "${{ steps.config.outputs.output-dir }}"
 
+      - name: Validate generated documentation
+        run: |
+          pnpm run postinstall
+          pnpm run lint:links
+
       - name: Create Pull Request for documentation changes
         id: create_pr
         env:

.github/workflows/generate-api-docs-confidential-contracts.yml

@@ -0,0 +1,165 @@
+# Docs Repository Receiver - Non-Versioned Paths
+# Receives trigger from openzeppelin-confidential-contracts and generates API docs
+
+name: Generate API Docs - Confidential Contracts
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag_name:
+        description: 'Tag name or commit SHA to generate docs from'
+        required: true
+        type: string
+        default: 'v0.4.0'
+      trigger_type:
+        description: 'Trigger type (tag or commit)'
+        required: false
+        type: string
+        default: 'tag'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+env:
+  SOURCE_REPO: 'OpenZeppelin/openzeppelin-confidential-contracts'
+  SOURCE_REPO_URL: 'https://github.com/OpenZeppelin/openzeppelin-confidential-contracts.git'
+  BASE_OUTPUT_PATH: 'content/confidential-contracts'
+  USE_VERSIONED_PATHS: 'false'
+
+jobs:
+  generate-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Log trigger information
+        run: |
+          echo "🚀 API Documentation Generation Triggered"
+          echo "📦 Repository: ${{ env.SOURCE_REPO }}"
+          echo "🏷️  Tag/Ref: ${{ inputs.tag_name }}"
+          echo "📋 Trigger type: ${{ inputs.trigger_type }}"
+
+      - name: Checkout docs repository
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.17.1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Determine output directory
+        id: config
+        run: |
+          TAG_NAME="${{ inputs.tag_name }}"
+          TRIGGER_TYPE="${{ inputs.trigger_type }}"
+          BASE_PATH="${{ env.BASE_OUTPUT_PATH }}"
+          USE_VERSIONED="${{ env.USE_VERSIONED_PATHS }}"
+
+          if [[ "$USE_VERSIONED" == "false" ]]; then
+            OUTPUT_DIR="${BASE_PATH}/api"
+            echo "📁 Using non-versioned path"
+          elif [[ "$TRIGGER_TYPE" == "commit" ]]; then
+            OUTPUT_DIR="${BASE_PATH}/latest/api"
+            echo "🔄 Using latest path for commit-based trigger"
+          else
+            if [[ "$TAG_NAME" =~ v([0-9]+) ]]; then
+              MAJOR_VERSION="${BASH_REMATCH[1]}"
+              OUTPUT_DIR="${BASE_PATH}/${MAJOR_VERSION}.x/api"
+              echo "📊 Detected version: ${MAJOR_VERSION}.x"
+            else
+              OUTPUT_DIR="${BASE_PATH}/latest/api"
+              echo "⚠️  Non-standard tag format, using latest"
+            fi
+          fi
+
+          echo "📂 Output directory: $OUTPUT_DIR"
+          echo "output-dir=$OUTPUT_DIR" >> $GITHUB_OUTPUT
+
+      - name: Generate API Documentation
+        run: |
+          echo "🔄 Generating API documentation..."
+
+          node scripts/generate-api-docs.js \
+            --repo "${{ env.SOURCE_REPO_URL }}" \
+            --branch "${{ inputs.tag_name }}" \
+            --api-output "${{ steps.config.outputs.output-dir }}"
+
+      - name: Validate generated documentation
+        run: |
+          pnpm run postinstall
+          pnpm run lint:links
+
+      - name: Create Pull Request for documentation changes
+        id: create_pr
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git config --local user.email "docs-automation@openzeppelin.com"
+          git config --local user.name "OpenZeppelin Docs Bot"
+
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "📝 Creating branch and committing documentation changes..."
+
+            BRANCH_NAME="docs/api-update-${{ env.SOURCE_REPO }}-${{ inputs.tag_name }}"
+            BRANCH_NAME=$(echo "$BRANCH_NAME" | sed 's/\//-/g' | sed 's/OpenZeppelin-//g')
+
+            git checkout -b "$BRANCH_NAME"
+            git add .
+            git commit -m "Update API docs for ${{ env.SOURCE_REPO }} ${{ inputs.tag_name }}
+
+            - Repository: ${{ env.SOURCE_REPO }}
+            - Ref: ${{ inputs.tag_name }}
+            - Trigger: ${{ inputs.trigger_type }}
+            - Output: ${{ steps.config.outputs.output-dir }}
+            - Timestamp: $(date -u '+%Y-%m-%d %H:%M:%S UTC')
+
+            Auto-generated via workflow_dispatch"
+
+            git push origin "$BRANCH_NAME"
+
+            gh pr create --title "[CI] Update API docs for ${{ env.SOURCE_REPO }} ${{ inputs.tag_name }}" \
+                     --body "## API Documentation Update
+
+            This Pull Request updates the API documentation.
+
+            ### Source Information
+            - **Repository:** ${{ env.SOURCE_REPO }}
+            - **Reference:** ${{ inputs.tag_name }}
+            - **Trigger Type:** ${{ inputs.trigger_type }}
+            - **Output Directory:** ${{ steps.config.outputs.output-dir }}
+            - **Timestamp:** $(date -u '+%Y-%m-%d %H:%M:%S UTC')
+
+            Auto-generated via workflow_dispatch" \
+                     --base main \
+                     --head "$BRANCH_NAME" || echo "⚠️  Pull Request creation failed"
+
+            echo "✅ Pull Request created successfully"
+            echo "pr-created=true" >> $GITHUB_OUTPUT
+          else
+            echo "ℹ️  No changes detected - documentation is up to date"
+            echo "pr-created=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create job summary
+        run: |
+          echo "## 📚 API Documentation Generation Complete" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Source Information" >> $GITHUB_STEP_SUMMARY
+          echo "- **Repository:** ${{ env.SOURCE_REPO }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Reference:** ${{ inputs.tag_name }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Trigger Type:** ${{ inputs.trigger_type }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Output" >> $GITHUB_STEP_SUMMARY
+          echo "- **Directory:** ${{ steps.config.outputs.output-dir }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Status:** ✅ Complete" >> $GITHUB_STEP_SUMMARY

.github/workflows/generate-api-docs-contracts.yml

@@ -0,0 +1,166 @@
+# Docs Repository Receiver - Versioned Paths
+# Receives trigger from openzeppelin-contracts and generates API docs
+
+name: Generate API Docs - Contracts
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag_name:
+        description: 'Tag name or commit SHA to generate docs from'
+        required: true
+        type: string
+        default: 'v5.6.1'
+      trigger_type:
+        description: 'Trigger type (tag or commit)'
+        required: false
+        type: string
+        default: 'tag'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+env:
+  SOURCE_REPO: 'OpenZeppelin/openzeppelin-contracts'
+  SOURCE_REPO_URL: 'https://github.com/OpenZeppelin/openzeppelin-contracts.git'
+  BASE_OUTPUT_PATH: 'content/contracts'
+  USE_VERSIONED_PATHS: 'true'
+
+jobs:
+  generate-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Log trigger information
+        run: |
+          echo "🚀 API Documentation Generation Triggered"
+          echo "📦 Repository: ${{ env.SOURCE_REPO }}"
+          echo "🏷️  Tag/Ref: ${{ inputs.tag_name }}"
+          echo "📋 Trigger type: ${{ inputs.trigger_type }}"
+
+      - name: Checkout docs repository
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.17.1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Determine output directory
+        id: config
+        run: |
+          TAG_NAME="${{ inputs.tag_name }}"
+          TRIGGER_TYPE="${{ inputs.trigger_type }}"
+          BASE_PATH="${{ env.BASE_OUTPUT_PATH }}"
+          USE_VERSIONED="${{ env.USE_VERSIONED_PATHS }}"
+
+          if [[ "$USE_VERSIONED" == "false" ]]; then
+            OUTPUT_DIR="${BASE_PATH}/api"
+            echo "📁 Using non-versioned path"
+          elif [[ "$TRIGGER_TYPE" == "commit" ]]; then
+            OUTPUT_DIR="${BASE_PATH}/latest/api"
+            echo "🔄 Using latest path for commit-based trigger"
+          else
+            # Extract major version from tag (v5.6.1 -> 5, v5.6.0 -> 5)
+            if [[ "$TAG_NAME" =~ v([0-9]+) ]]; then
+              MAJOR_VERSION="${BASH_REMATCH[1]}"
+              OUTPUT_DIR="${BASE_PATH}/${MAJOR_VERSION}.x/api"
+              echo "📊 Detected version: ${MAJOR_VERSION}.x"
+            else
+              OUTPUT_DIR="${BASE_PATH}/latest/api"
+              echo "⚠️  Non-standard tag format, using latest"
+            fi
+          fi
+
+          echo "📂 Output directory: $OUTPUT_DIR"
+          echo "output-dir=$OUTPUT_DIR" >> $GITHUB_OUTPUT
+
+      - name: Generate API Documentation
+        run: |
+          echo "🔄 Generating API documentation..."
+
+          node scripts/generate-api-docs.js \
+            --repo "${{ env.SOURCE_REPO_URL }}" \
+            --branch "${{ inputs.tag_name }}" \
+            --api-output "${{ steps.config.outputs.output-dir }}"
+
+      - name: Validate generated documentation
+        run: |
+          pnpm run postinstall
+          pnpm run lint:links
+
+      - name: Create Pull Request for documentation changes
+        id: create_pr
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git config --local user.email "docs-automation@openzeppelin.com"
+          git config --local user.name "OpenZeppelin Docs Bot"
+
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "📝 Creating branch and committing documentation changes..."
+
+            BRANCH_NAME="docs/api-update-${{ env.SOURCE_REPO }}-${{ inputs.tag_name }}"
+            BRANCH_NAME=$(echo "$BRANCH_NAME" | sed 's/\//-/g' | sed 's/OpenZeppelin-//g')
+
+            git checkout -b "$BRANCH_NAME"
+            git add .
+            git commit -m "Update API docs for ${{ env.SOURCE_REPO }} ${{ inputs.tag_name }}
+
+            - Repository: ${{ env.SOURCE_REPO }}
+            - Ref: ${{ inputs.tag_name }}
+            - Trigger: ${{ inputs.trigger_type }}
+            - Output: ${{ steps.config.outputs.output-dir }}
+            - Timestamp: $(date -u '+%Y-%m-%d %H:%M:%S UTC')
+
+            Auto-generated via workflow_dispatch"
+
+            git push origin "$BRANCH_NAME"
+
+            gh pr create --title "[CI] Update API docs for ${{ env.SOURCE_REPO }} ${{ inputs.tag_name }}" \
+                     --body "## API Documentation Update
+
+            This Pull Request updates the API documentation.
+
+            ### Source Information
+            - **Repository:** ${{ env.SOURCE_REPO }}
+            - **Reference:** ${{ inputs.tag_name }}
+            - **Trigger Type:** ${{ inputs.trigger_type }}
+            - **Output Directory:** ${{ steps.config.outputs.output-dir }}
+            - **Timestamp:** $(date -u '+%Y-%m-%d %H:%M:%S UTC')
+
+            Auto-generated via workflow_dispatch" \
+                     --base main \
+                     --head "$BRANCH_NAME" || echo "⚠️  Pull Request creation failed"
+
+            echo "✅ Pull Request created successfully"
+            echo "pr-created=true" >> $GITHUB_OUTPUT
+          else
+            echo "ℹ️  No changes detected - documentation is up to date"
+            echo "pr-created=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create job summary
+        run: |
+          echo "## 📚 API Documentation Generation Complete" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Source Information" >> $GITHUB_STEP_SUMMARY
+          echo "- **Repository:** ${{ env.SOURCE_REPO }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Reference:** ${{ inputs.tag_name }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Trigger Type:** ${{ inputs.trigger_type }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Output" >> $GITHUB_STEP_SUMMARY
+          echo "- **Directory:** ${{ steps.config.outputs.output-dir }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Status:** ✅ Complete" >> $GITHUB_STEP_SUMMARY

.gitignore

@@ -26,6 +26,9 @@ yarn-error.log*
 package-lock.json
 yarn.lock
 
+# temp dirs from generate-api-docs.js
+temp-*/
+
 # others
 .env*.local
 .vercel