forked from cerc-io/snowballtools-base
82 lines
2.6 KiB
JavaScript
Executable File
82 lines
2.6 KiB
JavaScript
Executable File
#!/usr/bin/env node
|
|
|
|
/**
|
|
* Script to generate TypeDoc documentation for the monorepo
|
|
*/
|
|
|
|
const { execSync } = require('child_process');
|
|
const fs = require('fs');
|
|
const path = require('path');
|
|
const rimraf = require('rimraf');
|
|
|
|
// Ensure docs directory exists
|
|
const docsDir = path.join(__dirname, '..', 'docs');
|
|
if (!fs.existsSync(docsDir)) {
|
|
fs.mkdirSync(docsDir, { recursive: true });
|
|
}
|
|
|
|
// Run TypeDoc
|
|
console.log('Generating documentation...');
|
|
try {
|
|
// Use npx to run TypeDoc
|
|
execSync('npx typedoc', { stdio: 'inherit' });
|
|
console.log('Documentation generated successfully in the docs/ directory');
|
|
|
|
console.log('\nCI/CD Approach for Documentation:');
|
|
console.log('1. Add docs/ to your .gitignore file to prevent committing generated docs');
|
|
console.log('2. Set up a GitHub Action workflow that:');
|
|
console.log(' - Runs on push to main/develop/develop-qwrk branches');
|
|
console.log(' - Generates documentation using this script');
|
|
console.log(' - Deploys the generated docs to GitHub Pages');
|
|
|
|
console.log('\nExample GitHub Action workflow (.github/workflows/docs.yml):');
|
|
console.log(`
|
|
name: Generate and Deploy Docs
|
|
|
|
on:
|
|
push:
|
|
branches: [ main, master, develop, develop-qwrk ] # Trigger on these branches
|
|
workflow_dispatch: # Allow manual triggering
|
|
|
|
jobs:
|
|
build-and-deploy:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v3
|
|
|
|
- name: Setup Node.js
|
|
uses: actions/setup-node@v3
|
|
with:
|
|
node-version: '16'
|
|
cache: 'yarn'
|
|
|
|
- name: Install dependencies
|
|
run: yarn install --frozen-lockfile
|
|
|
|
- name: Generate documentation
|
|
run: node scripts/generate-docs.js
|
|
|
|
- name: Deploy to GitHub Pages
|
|
uses: JamesIves/github-pages-deploy-action@v4
|
|
with:
|
|
branch: gh-pages
|
|
folder: docs
|
|
clean: true
|
|
`);
|
|
|
|
console.log('\nThis way, your documentation will be:');
|
|
console.log('- Generated automatically when you push to main, develop, or develop-qwrk');
|
|
console.log('- Deployed to GitHub Pages without cluttering your main branch');
|
|
console.log('- Available at https://[username].github.io/[repository]/');
|
|
|
|
// Clean up docs directory if the --clean flag is provided
|
|
if (process.argv.includes('--clean')) {
|
|
console.log('\nCleaning up docs directory...');
|
|
rimraf.sync(docsDir);
|
|
console.log('Docs directory removed. Documentation will only be available through GitHub Pages.');
|
|
}
|
|
|
|
} catch (error) {
|
|
console.error('Error generating documentation:', error.message);
|
|
process.exit(1);
|
|
}
|