Skip to content

Commit b8b478a

Browse files
stevedylandevstevedylandev
committed
feat: added generate-api-docs-community-contracts.yml
1 parent 4f61f1a commit b8b478a

1 file changed

Lines changed: 172 additions & 0 deletions

File tree

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

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# TEMPLATE: Docs Repository Receiver - Non-Versioned Paths
2+
# Copy to: .github/workflows/generate-api-docs-{YOUR_CONTRACT}.yml (in docs repo)
3+
#
4+
# SETUP INSTRUCTIONS:
5+
# 1. Update workflow name (line 15)
6+
# 2. Update default tag_name and trigger_type (lines 13 and 18)
7+
# 3. Configure environment variables (lines 21-24):
8+
# - SOURCE_REPO: GitHub owner/repo name
9+
# - SOURCE_REPO_URL: Full git URL
10+
# - BASE_OUTPUT_PATH: Where to put generated docs
11+
# - USE_VERSIONED_PATHS: Keep as 'false' for non-versioned paths
12+
13+
name: Generate API Docs - Community Contracts
14+
15+
on:
16+
workflow_dispatch:
17+
inputs:
18+
tag_name:
19+
description: 'Tag name or commit SHA to generate docs from'
20+
required: true
21+
type: string
22+
default: 'main' # TODO: Update default ref
23+
trigger_type:
24+
description: 'Trigger type (tag or commit)'
25+
required: false
26+
type: string
27+
default: 'commit' # TODO: Update if using tags
28+
29+
# TODO: Configure these environment variables for your contract
30+
env:
31+
SOURCE_REPO: 'OpenZeppelin/openzeppelin-community-contracts'
32+
SOURCE_REPO_URL: 'https://github.com/OpenZeppelin/openzeppelin-community-contracts.git'
33+
BASE_OUTPUT_PATH: 'content/community-contracts'
34+
USE_VERSIONED_PATHS: 'false'
35+
36+
jobs:
37+
generate-docs:
38+
runs-on: ubuntu-latest
39+
40+
steps:
41+
- name: Log trigger information
42+
run: |
43+
echo "🚀 API Documentation Generation Triggered"
44+
echo "📦 Repository: ${{ env.SOURCE_REPO }}"
45+
echo "🏷️ Tag/Ref: ${{ inputs.tag_name }}"
46+
echo "📋 Trigger type: ${{ inputs.trigger_type }}"
47+
48+
- name: Checkout docs repository
49+
uses: actions/checkout@v4
50+
with:
51+
token: ${{ secrets.GITHUB_TOKEN }}
52+
53+
- name: Setup pnpm
54+
uses: pnpm/action-setup@v4
55+
with:
56+
version: 10.17.1
57+
58+
- name: Setup Node.js
59+
uses: actions/setup-node@v4
60+
with:
61+
node-version: '22'
62+
cache: 'pnpm'
63+
64+
- name: Install dependencies
65+
run: pnpm install --frozen-lockfile
66+
67+
- name: Determine output directory
68+
id: config
69+
run: |
70+
TAG_NAME="${{ inputs.tag_name }}"
71+
TRIGGER_TYPE="${{ inputs.trigger_type }}"
72+
BASE_PATH="${{ env.BASE_OUTPUT_PATH }}"
73+
USE_VERSIONED="${{ env.USE_VERSIONED_PATHS }}"
74+
75+
if [[ "$USE_VERSIONED" == "false" ]]; then
76+
# Non-versioned path (e.g., community-contracts/api)
77+
OUTPUT_DIR="${BASE_PATH}/api"
78+
echo "📁 Using non-versioned path"
79+
elif [[ "$TRIGGER_TYPE" == "commit" ]]; then
80+
# Commit-based trigger uses /latest/api
81+
OUTPUT_DIR="${BASE_PATH}/latest/api"
82+
echo "🔄 Using latest path for commit-based trigger"
83+
else
84+
# Tag-based trigger: extract major version
85+
if [[ "$TAG_NAME" =~ v([0-9]+) ]]; then
86+
MAJOR_VERSION="${BASH_REMATCH[1]}"
87+
OUTPUT_DIR="${BASE_PATH}/${MAJOR_VERSION}.x/api"
88+
echo "📊 Detected version: ${MAJOR_VERSION}.x"
89+
else
90+
# Fallback for non-standard tags
91+
OUTPUT_DIR="${BASE_PATH}/latest/api"
92+
echo "⚠️ Non-standard tag format, using latest"
93+
fi
94+
fi
95+
96+
echo "📂 Output directory: $OUTPUT_DIR"
97+
echo "output-dir=$OUTPUT_DIR" >> $GITHUB_OUTPUT
98+
99+
- name: Generate API Documentation
100+
run: |
101+
echo "🔄 Generating API documentation..."
102+
103+
node scripts/generate-api-docs.js \
104+
--repo "${{ env.SOURCE_REPO_URL }}" \
105+
--branch "${{ inputs.tag_name }}" \
106+
--api-output "${{ steps.config.outputs.output-dir }}"
107+
108+
- name: Create Pull Request for documentation changes
109+
id: create_pr
110+
env:
111+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
112+
run: |
113+
git config --local user.email "docs-automation@openzeppelin.com"
114+
git config --local user.name "OpenZeppelin Docs Bot"
115+
116+
if [ -n "$(git status --porcelain)" ]; then
117+
echo "📝 Creating branch and committing documentation changes..."
118+
119+
# Create unique branch name
120+
BRANCH_NAME="docs/api-update-${{ env.SOURCE_REPO }}-${{ inputs.tag_name }}"
121+
BRANCH_NAME=$(echo "$BRANCH_NAME" | sed 's/\//-/g' | sed 's/OpenZeppelin-//g')
122+
123+
git checkout -b "$BRANCH_NAME"
124+
git add .
125+
git commit -m "📚 Update API docs for ${{ env.SOURCE_REPO }} ${{ inputs.tag_name }}
126+
127+
- Repository: ${{ env.SOURCE_REPO }}
128+
- Ref: ${{ inputs.tag_name }}
129+
- Trigger: ${{ inputs.trigger_type }}
130+
- Output: ${{ steps.config.outputs.output-dir }}
131+
- Timestamp: $(date -u '+%Y-%m-%d %H:%M:%S UTC')
132+
133+
Auto-generated via workflow_dispatch"
134+
135+
git push origin "$BRANCH_NAME"
136+
137+
# Create Pull Request
138+
gh pr create --title "[CI] Update API docs for ${{ env.SOURCE_REPO }} ${{ inputs.tag_name }}" \
139+
--body "## API Documentation Update
140+
141+
This Pull Request updates the API documentation.
142+
143+
### Source Information
144+
- **Repository:** ${{ env.SOURCE_REPO }}
145+
- **Reference:** ${{ inputs.tag_name }}
146+
- **Trigger Type:** ${{ inputs.trigger_type }}
147+
- **Output Directory:** ${{ steps.config.outputs.output-dir }}
148+
- **Timestamp:** $(date -u '+%Y-%m-%d %H:%M:%S UTC')
149+
150+
Auto-generated via workflow_dispatch" \
151+
--base main \
152+
--head "$BRANCH_NAME" || echo "⚠️ Pull Request creation failed"
153+
154+
echo "✅ Pull Request created successfully"
155+
echo "pr-created=true" >> $GITHUB_OUTPUT
156+
else
157+
echo "ℹ️ No changes detected - documentation is up to date"
158+
echo "pr-created=false" >> $GITHUB_OUTPUT
159+
fi
160+
161+
- name: Create job summary
162+
run: |
163+
echo "## 📚 API Documentation Generation Complete" >> $GITHUB_STEP_SUMMARY
164+
echo "" >> $GITHUB_STEP_SUMMARY
165+
echo "### Source Information" >> $GITHUB_STEP_SUMMARY
166+
echo "- **Repository:** ${{ env.SOURCE_REPO }}" >> $GITHUB_STEP_SUMMARY
167+
echo "- **Reference:** ${{ inputs.tag_name }}" >> $GITHUB_STEP_SUMMARY
168+
echo "- **Trigger Type:** ${{ inputs.trigger_type }}" >> $GITHUB_STEP_SUMMARY
169+
echo "" >> $GITHUB_STEP_SUMMARY
170+
echo "### Output" >> $GITHUB_STEP_SUMMARY
171+
echo "- **Directory:** ${{ steps.config.outputs.output-dir }}" >> $GITHUB_STEP_SUMMARY
172+
echo "- **Status:** ✅ Complete" >> $GITHUB_STEP_SUMMARY

0 commit comments

Comments
 (0)