Skip to content

Commit 40c7f9c

Browse files
starichkovstarichkov
committed
Added JSDoc documentation system with GitHub Pages deployment
## Key Features - Complete JSDoc setup with comprehensive API documentation - Automated GitHub Pages deployment via optimized single-job workflow - Documentation coverage analysis with 80% threshold enforcement - Professional JSDoc comments throughout all source files - Quality control scripts for continuous validation ## New Infrastructure - .github/workflows/docs.yml - Optimized documentation CI/CD pipeline - DOCUMENTATION.md - Complete documentation system guide - scripts/check-docs-coverage.js - Coverage analysis and validation - scripts/version-docs.js - Documentation versioning system - jsdoc.config.json - JSDoc configuration ## Enhancements - Enhanced all source files with comprehensive JSDoc comments - Updated package.json with doc scripts and Node.js 22 LTS requirements - Updated GITHUB_ACTIONS.md for dual-workflow documentation - Quality gates ensure only validated docs are deployed Establishes professional-grade automated documentation with GitHub Pages integration.
1 parent 4184c8d commit 40c7f9c

15 files changed

Lines changed: 1735 additions & 76 deletions

‎.github/workflows/docs-multi-job.yml.backup‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
name: Generate and Deploy Documentation
2+
3+
on:
4+
push:
5+
branches: [ main, develop ]
6+
pull_request:
7+
branches: [ main ]
8+
release:
9+
types: [ published ]
10+
11+
jobs:
12+
# Single documentation generation job
13+
generate-docs:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- name: Checkout code
17+
uses: actions/checkout@v4
18+
19+
- name: Setup Node.js
20+
uses: actions/setup-node@v4
21+
with:
22+
node-version: '22'
23+
cache: 'npm'
24+
25+
- name: Install dependencies
26+
run: npm ci
27+
28+
- name: Generate documentation
29+
run: npm run docs
30+
31+
- name: Upload documentation artifacts
32+
uses: actions/upload-artifact@v4
33+
with:
34+
name: documentation
35+
path: docs/
36+
retention-days: 30
37+
38+
# Quality checks using generated documentation
39+
docs-quality:
40+
needs: generate-docs
41+
runs-on: ubuntu-latest
42+
steps:
43+
- name: Checkout code
44+
uses: actions/checkout@v4
45+
46+
- name: Setup Node.js
47+
uses: actions/setup-node@v4
48+
with:
49+
node-version: '22'
50+
cache: 'npm'
51+
52+
- name: Install dependencies
53+
run: npm ci
54+
55+
- name: Download generated documentation
56+
uses: actions/download-artifact@v4
57+
with:
58+
name: documentation
59+
path: docs/
60+
61+
- name: Check for broken links
62+
run: |
63+
# Install link checker
64+
npm install -g linkinator
65+
# Check generated documentation
66+
linkinator docs/ --recurse --silent
67+
68+
- name: Validate JSDoc coverage
69+
run: |
70+
# Custom script to check documentation coverage
71+
node scripts/check-docs-coverage.js
72+
73+
# Deploy to GitHub Pages using generated documentation
74+
deploy-docs:
75+
needs: [generate-docs, docs-quality]
76+
runs-on: ubuntu-latest
77+
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
78+
79+
# Required for GitHub Pages deployment
80+
permissions:
81+
contents: read
82+
pages: write
83+
id-token: write
84+
85+
environment:
86+
name: github-pages
87+
url: ${{ steps.deployment.outputs.page_url }}
88+
89+
steps:
90+
- name: Download generated documentation
91+
uses: actions/download-artifact@v4
92+
with:
93+
name: documentation
94+
path: docs/
95+
96+
- name: Setup Pages
97+
uses: actions/configure-pages@v3
98+
99+
- name: Upload to GitHub Pages
100+
uses: actions/upload-pages-artifact@v2
101+
with:
102+
path: docs/
103+
104+
- name: Deploy to GitHub Pages
105+
id: deployment
106+
uses: actions/deploy-pages@v2

‎.github/workflows/docs.yml‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
name: Generate and Deploy Documentation
2+
3+
on:
4+
push:
5+
branches: [ main, develop ]
6+
pull_request:
7+
branches: [ main ]
8+
release:
9+
types: [ published ]
10+
11+
jobs:
12+
# Single job for complete documentation pipeline
13+
docs-pipeline:
14+
runs-on: ubuntu-latest
15+
16+
# Required for GitHub Pages deployment
17+
permissions:
18+
contents: read
19+
pages: write
20+
id-token: write
21+
22+
environment:
23+
name: github-pages
24+
url: ${{ steps.deployment.outputs.page_url }}
25+
26+
steps:
27+
# 1. Setup phase (once)
28+
- name: Checkout code
29+
uses: actions/checkout@v4
30+
31+
- name: Setup Node.js
32+
uses: actions/setup-node@v4
33+
with:
34+
node-version: '22'
35+
cache: 'npm'
36+
37+
- name: Install dependencies
38+
run: npm ci
39+
40+
# 2. Build phase
41+
- name: Generate documentation
42+
run: npm run docs
43+
44+
# 3. Quality check phase
45+
- name: Install quality tools
46+
run: npm install -g linkinator
47+
48+
- name: Check for broken links
49+
run: linkinator docs/ --recurse --silent
50+
51+
- name: Validate JSDoc coverage
52+
run: node scripts/check-docs-coverage.js
53+
54+
# 4. Archive documentation (optional - for debugging)
55+
- name: Upload documentation artifacts
56+
if: failure() || github.event_name == 'pull_request'
57+
uses: actions/upload-artifact@v4
58+
with:
59+
name: documentation
60+
path: docs/
61+
retention-days: 7
62+
63+
# 5. Deploy phase (only on main branch pushes)
64+
- name: Setup Pages
65+
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
66+
uses: actions/configure-pages@v3
67+
68+
- name: Upload to GitHub Pages
69+
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
70+
uses: actions/upload-pages-artifact@v2
71+
with:
72+
path: docs/
73+
74+
- name: Deploy to GitHub Pages
75+
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
76+
id: deployment
77+
uses: actions/deploy-pages@v2

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
.idea/
22
node_modules/
33
coverage/
4+
docs/
5+
versioned-docs/
46

57
*.env

0 commit comments

Comments
 (0)