Skip to content

Commit 7b3b45c

Browse files
pankajvaghelapankajvaghela
committed
Add setup to auto-gen docs
1 parent a09a0c9 commit 7b3b45c

File tree

8 files changed

+653
-15
lines changed

8 files changed

+653
-15
lines changed

‎.github/workflows/update-docs.yml‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
name: "Update API Documentation"
2+
3+
on:
4+
workflow_run:
5+
workflows: ["CD: NPM publish with tag push"]
6+
types:
7+
- completed
8+
workflow_dispatch: # Allow manual trigger
9+
10+
jobs:
11+
update-docs:
12+
name: "Generate and Update API Docs"
13+
runs-on: ubuntu-latest
14+
# Only run if the release workflow succeeded
15+
if: ${{ github.event.workflow_run.conclusion == 'success' || github.event_name == 'workflow_dispatch' }}
16+
17+
permissions:
18+
contents: write
19+
pull-requests: write
20+
21+
steps:
22+
- name: Checkout code
23+
uses: actions/checkout@v4
24+
with:
25+
ref: dev-v6 # or your main branch
26+
fetch-depth: 0
27+
28+
- name: Set up Node.js
29+
uses: actions/setup-node@v4
30+
with:
31+
node-version: '24.x'
32+
cache: 'yarn'
33+
34+
- name: Install dependencies
35+
run: yarn install --frozen-lockfile
36+
37+
- name: Generate API documentation
38+
run: node scripts/generate-api-docs.mjs
39+
40+
- name: Get version from latest tag
41+
id: get_version
42+
run: |
43+
# Get the latest tag
44+
VERSION=$(git describe --tags --abbrev=0 2>/dev/null || echo "unknown")
45+
# Remove 'v' prefix if present
46+
VERSION=${VERSION#v}
47+
echo "version=$VERSION" >> $GITHUB_OUTPUT
48+
echo "📦 Detected version from tag: $VERSION"
49+
50+
- name: Check for changes
51+
id: check_changes
52+
run: |
53+
if git diff --quiet apps/sequelize-guard-docs/content/docs/api/; then
54+
echo "has_changes=false" >> $GITHUB_OUTPUT
55+
else
56+
echo "has_changes=true" >> $GITHUB_OUTPUT
57+
fi
58+
59+
- name: Create Pull Request
60+
if: steps.check_changes.outputs.has_changes == 'true'
61+
uses: peter-evans/create-pull-request@v7
62+
with:
63+
token: ${{ secrets.GITHUB_TOKEN }}
64+
commit-message: "docs: update API documentation for v${{ steps.get_version.outputs.version }}"
65+
title: "docs: Update API documentation for v${{ steps.get_version.outputs.version }}"
66+
body: |
67+
## 📚 API Documentation Update
68+
69+
This PR updates the API documentation after the **v${{ steps.get_version.outputs.version }}** release.
70+
71+
### 🎉 Release Version
72+
**v${{ steps.get_version.outputs.version }}**
73+
74+
### 📝 Changes
75+
- Auto-generated API documentation from TypeScript source code
76+
- Updated `apps/sequelize-guard-docs/content/docs/api/`
77+
- Generated **${{ steps.check_changes.outputs.file_count }}** documentation files
78+
79+
### 🤖 Generated by
80+
- **Workflow:** `update-docs.yml`
81+
- **Triggered by:** Release workflow completion
82+
- **Script:** `scripts/generate-api-docs.mjs`
83+
- **Run:** [#${{ github.run_number }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
84+
85+
---
86+
87+
**Note:** This is an automated PR. Please review the changes before merging.
88+
branch: docs/update-api-v${{ steps.get_version.outputs.version }}-${{ github.run_number }}
89+
base: dev-v6
90+
labels: documentation,automated
91+
assignees: ${{ github.actor }}
92+
93+
- name: No changes detected
94+
if: steps.check_changes.outputs.has_changes == 'false'
95+
run: echo "✅ No changes detected in API documentation"

‎README.md‎

Lines changed: 27 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ For comprehensive guides, API reference, and examples, visit our documentation:
111111

112112
### Migration
113113

114-
- **[Migration Guide v5 → v6](https://sequelize-guard.js.org/migration/v6)** - Complete guide for upgrading from v5 to v6
114+
- **[Migration Guide to v6](https://sequelize-guard.js.org/migration/upgrade-to-v6)** - Complete guide for upgrading to v6
115115

116116
### Core Concepts
117117

@@ -166,16 +166,33 @@ We love contributions! SequelizeGuard is open source and we welcome contribution
166166
- ✅ Test coverage improvements
167167
- 💡 Ideas and suggestions
168168

169-
### How to Contribute
169+
```bash
170+
# Clone the repository
171+
git clone https://github.com/lotivo/sequelize-guard.git
172+
cd sequelize-guard
173+
174+
# Install dependencies
175+
yarn install
176+
177+
# Run tests
178+
yarn test
179+
180+
# Build
181+
yarn build
182+
```
183+
184+
### Documentation
185+
186+
#### Generating API Documentation
187+
188+
API documentation is automatically generated from TypeScript source code:
189+
190+
```bash
191+
# Generate API docs manually
192+
yarn docs:generate
193+
```
170194

171-
1. Fork the repository
172-
2. Create a feature branch: `git checkout -b feature/my-feature`
173-
3. Install dependencies: `yarn install`
174-
4. Make your changes and add tests
175-
5. Run tests: `yarn test`
176-
6. Run linting: `yarn lint`
177-
7. Commit using [Conventional Commits](https://www.conventionalcommits.org/): `git commit -m "feat: add feature"`
178-
8. Push and open a Pull Request
195+
The API documentation is automatically updated after each release via GitHub Actions. See [scripts/README.md](scripts/README.md) for details.
179196

180197
### Reporting Issues
181198

‎docs/DOCS_AUTOMATION.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# Documentation Automation
2+
3+
This document describes the automated documentation generation process for sequelize-guard.
4+
5+
## Overview
6+
7+
API documentation is automatically generated from TypeScript source code and updated after each npm release.
8+
9+
## Process Flow
10+
11+
```
12+
1. Push tag (e.g., v6.0.1)
13+
↓
14+
2. Release workflow runs (.github/workflows/release.yml)
15+
- Runs tests
16+
- Builds package
17+
- Publishes to npm
18+
↓
19+
3. Update docs workflow triggers (.github/workflows/update-docs.yml)
20+
- Generates API docs from source
21+
- Creates PR with updated documentation
22+
↓
23+
4. Review and merge PR
24+
- Documentation site automatically updates
25+
```
26+
27+
## Files Involved
28+
29+
### Scripts
30+
31+
- **`scripts/generate-api-docs.mjs`** - Main script that generates API documentation
32+
- **`typedoc.json`** - TypeDoc configuration
33+
34+
### Workflows
35+
36+
- **`.github/workflows/release.yml`** - Handles npm publishing
37+
- **`.github/workflows/update-docs.yml`** - Handles documentation updates
38+
39+
### Output
40+
41+
- **`apps/sequelize-guard-docs/content/docs/api.mdx`** - Generated API documentation
42+
43+
## Manual Usage
44+
45+
### Generate API Documentation
46+
47+
```bash
48+
# Install dependencies (if not already installed)
49+
yarn install
50+
51+
# Generate API documentation
52+
yarn docs:generate
53+
```
54+
55+
This will:
56+
57+
1. Run TypeDoc to extract API information from `packages/sequelize-guard/src/`
58+
2. Convert the output to MDX format
59+
3. Write to `apps/sequelize-guard-docs/content/docs/api.mdx`
60+
61+
### Test Locally
62+
63+
```bash
64+
# Generate docs
65+
yarn docs:generate
66+
67+
# Check the changes
68+
git diff apps/sequelize-guard-docs/content/docs/api.mdx
69+
70+
# If satisfied, commit
71+
git add apps/sequelize-guard-docs/content/docs/api.mdx
72+
git commit -m "docs: update API documentation"
73+
```
74+
75+
## Customization
76+
77+
### Modify Output Format
78+
79+
Edit `scripts/generate-api-docs.mjs`:
80+
81+
```javascript
82+
function generateMDX(apiJson) {
83+
// Customize the MDX output here
84+
// Modify frontmatter, content structure, etc.
85+
}
86+
```
87+
88+
### Change TypeDoc Configuration
89+
90+
Edit `typedoc.json`:
91+
92+
```json
93+
{
94+
"entryPoints": ["./packages/sequelize-guard/src/index.ts"],
95+
"excludePrivate": true
96+
// Add more options as needed
97+
}
98+
```
99+
100+
## Workflow Configuration
101+
102+
### Update Docs Workflow
103+
104+
The workflow is triggered automatically after a successful release, but can also be run manually:
105+
106+
1. Go to **Actions** tab on GitHub
107+
2. Select **"Update API Documentation"** workflow
108+
3. Click **"Run workflow"**
109+
110+
### Customize Workflow
111+
112+
Edit `.github/workflows/update-docs.yml`:
113+
114+
- Change the target branch (default: `dev-v6`)
115+
- Modify PR labels or assignees
116+
- Adjust commit messages
117+
118+
## Dependencies
119+
120+
The following packages are required (already in `package.json`):
121+
122+
```json
123+
{
124+
"devDependencies": {
125+
"typedoc": "^0.27.5",
126+
"typedoc-plugin-markdown": "^4.4.1"
127+
}
128+
}
129+
```
130+
131+
## Troubleshooting
132+
133+
### Workflow Not Triggering
134+
135+
**Problem:** Update docs workflow doesn't run after release
136+
137+
**Solution:**
138+
139+
- Check that release workflow completed successfully
140+
- Verify workflow permissions in repository settings
141+
- Manually trigger the workflow from Actions tab
142+
143+
### Generated Documentation is Empty
144+
145+
**Problem:** API documentation file is empty or incomplete
146+
147+
**Solution:**
148+
149+
- Check TypeDoc configuration in `typedoc.json`
150+
- Verify entry points are correct
151+
- Run `yarn docs:generate` locally to debug
152+
153+
### PR Not Created
154+
155+
**Problem:** Workflow runs but no PR is created
156+
157+
**Solution:**
158+
159+
- Check if there are actual changes in the API documentation
160+
- Verify GitHub token has correct permissions
161+
- Check workflow logs for errors
162+
163+
## Best Practices
164+
165+
1. **Review PRs Carefully** - Always review auto-generated PRs before merging
166+
2. **Keep Script Updated** - Update `generate-api-docs.mjs` as API evolves
167+
3. **Test Locally First** - Run `yarn docs:generate` locally before pushing changes
168+
4. **Version Documentation** - Consider adding version tags to generated docs
169+
170+
## Future Improvements
171+
172+
Potential enhancements to consider:
173+
174+
- [ ] Add more detailed API examples in generated docs
175+
- [ ] Include parameter descriptions from JSDoc comments
176+
- [ ] Generate separate pages for each major class
177+
- [ ] Add interactive API playground
178+
- [ ] Version-specific documentation archives
179+
180+
## Support
181+
182+
For issues related to documentation automation:
183+
184+
1. Check this document first
185+
2. Review workflow logs in GitHub Actions
186+
3. Open an issue with the `documentation` label
187+
4. Tag @pankajvaghela for assistance
188+
189+
---
190+
191+
**Last Updated:** December 2025
192+
**Maintainer:** Pankaj Vaghela

‎package.json‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,8 @@
3333
"format:staged": "prettier --write",
3434
"lint:staged": "eslint --fix --max-warnings 0",
3535
"lint:staged:js": "eslint --fix",
36-
"pre-commit": "yarn lint-staged && tsc --noEmit"
36+
"pre-commit": "yarn lint-staged && tsc --noEmit",
37+
"docs:generate": "node scripts/generate-api-docs.mjs"
3738
},
3839
"devDependencies": {
3940
"@eslint/js": "^9.39.1",
@@ -69,6 +70,8 @@
6970
"rollup": "^4.53.3",
7071
"sqlite3": "^5.1.7",
7172
"tslib": "^2.3.0",
73+
"typedoc": "^0.28.2",
74+
"typedoc-plugin-markdown": "^4.9.0",
7275
"typescript": "^5.9.3",
7376
"vite": "^7.2.2",
7477
"vite-plugin-dts": "^4.5.4",

0 commit comments

Comments
 (0)
⚡