-
Notifications
You must be signed in to change notification settings - Fork 39
[MOB-12295] publish docs to netlify #736
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
1087275
chore: add Netlify configuration and deployment workflow for document…
lposen a8d1d94
docs: update README to enhance API documentation section and rename s…
lposen 05825c5
docs: add documentation deployment setup for Netlify with GitHub Actions
lposen 4aa8500
fix: update label from 'docs' to 'documentation' in deployment workfl…
lposen 2ce01cd
chore: update permissions in deployment workflow for documentation an…
lposen c361895
chore: update Netlify action version in deployment workflow for consi…
lposen File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Some comments aren't visible on the classic Files Changed page.
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,83 @@ | ||
| name: Deploy Documentation to Netlify | ||
|
|
||
| on: | ||
| push: | ||
| branches: | ||
| - master | ||
| - main | ||
| pull_request: | ||
| types: [opened, synchronize, labeled, unlabeled] | ||
| workflow_dispatch: # Allow manual triggering | ||
|
|
||
| jobs: | ||
| deploy-docs: | ||
| runs-on: ubuntu-latest | ||
| permissions: | ||
| contents: read | ||
| pull-requests: write | ||
| issues: write | ||
| # Only run on master/main pushes or PRs with "documentation" label | ||
| if: | | ||
| github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main') || | ||
| github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'documentation') || | ||
| github.event_name == 'workflow_dispatch' | ||
|
|
||
| steps: | ||
| - name: Checkout code | ||
| uses: actions/checkout@v4 | ||
| with: | ||
| fetch-depth: 0 # Fetch full history for proper git info | ||
|
|
||
| - name: Setup | ||
| uses: ./.github/actions/setup | ||
|
|
||
| - name: Build documentation | ||
| run: yarn docs | ||
|
|
||
| - name: Determine deployment type | ||
| id: deployment-type | ||
| run: | | ||
| if [[ "${{ github.event_name }}" == "push" ]]; then | ||
| echo "type=production" >> $GITHUB_OUTPUT | ||
| echo "message=Deploying to production site" >> $GITHUB_OUTPUT | ||
| else | ||
| echo "type=preview" >> $GITHUB_OUTPUT | ||
| echo "message=Deploying preview for PR #${{ github.event.number }}" >> $GITHUB_OUTPUT | ||
| fi | ||
|
|
||
| - name: Show deployment info | ||
| run: | | ||
| echo "🚀 ${{ steps.deployment-type.outputs.message }}" | ||
| echo "Branch: ${{ github.ref_name }}" | ||
| echo "Commit: ${{ github.sha }}" | ||
| if [[ "${{ github.event_name }}" == "pull_request" ]]; then | ||
| echo "Deployment alias: ${{ github.head_ref }}" | ||
| fi | ||
|
|
||
| - name: Deploy to Netlify (Production) | ||
| if: github.event_name == 'push' | ||
| uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654 | ||
| with: | ||
| publish-dir: "./docs" | ||
| production-branch: master | ||
| github-token: ${{ secrets.GITHUB_TOKEN }} | ||
| deploy-message: "${{ steps.deployment-type.outputs.message }}" | ||
| enable-commit-comment: true | ||
| env: | ||
| NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} | ||
| NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }} | ||
|
|
||
| - name: Deploy to Netlify (Preview) | ||
| if: github.event_name == 'pull_request' | ||
| uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654 # v3.0 | ||
| with: | ||
| publish-dir: "./docs" | ||
| production-branch: master | ||
| github-token: ${{ secrets.GITHUB_TOKEN }} | ||
| deploy-message: "${{ steps.deployment-type.outputs.message }}" | ||
| alias: ${{ github.head_ref }} | ||
| enable-pull-request-comment: true | ||
| overwrites-pull-request-comment: true | ||
| env: | ||
| NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} | ||
| NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }} | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -89,3 +89,6 @@ android/generated | |
| .xcode.env.local | ||
| coverage/ | ||
| docs/ | ||
|
|
||
| # Local Netlify folder | ||
| .netlify | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,120 @@ | ||
| # Documentation Deployment Setup | ||
|
|
||
| This document explains how to set up automatic documentation deployment to Netlify when merging to master or when using the "docs" label on pull requests. | ||
|
|
||
| ## Overview | ||
|
|
||
| The project uses GitHub Actions to automatically build and deploy documentation to Netlify in two scenarios: | ||
|
|
||
| 1. **Production Deployment**: When changes are merged to the master branch | ||
| 2. **Preview Deployment**: When a pull request has the "docs" label | ||
|
|
||
| The documentation is generated using TypeDoc and includes API documentation, coverage reports, and interactive navigation. | ||
|
|
||
| ## Deployment Triggers | ||
|
|
||
| ### Production Deployment | ||
| - Automatically triggers on pushes to `master` or `main` branches | ||
| - Deploys to the production Netlify site | ||
| - Updates the main documentation URL | ||
|
|
||
| ### Preview Deployment | ||
| - Triggers on pull requests with the "docs" label | ||
|
||
| - Creates a preview deployment for testing documentation changes | ||
| - Adds a comment to the PR with the preview URL | ||
| - Perfect for reviewing documentation changes before merging | ||
|
|
||
| ## How to Use Preview Deployments | ||
|
|
||
| 1. Create a pull request with documentation changes | ||
| 2. Add the "docs" label to the pull request | ||
| 3. The workflow will automatically build and deploy a preview | ||
| 4. Check the PR comments for the preview URL | ||
| 5. Review the changes and merge when ready | ||
|
|
||
| ## Setup Instructions | ||
|
|
||
| ### 1. Netlify Setup | ||
|
|
||
| 1. Go to [Netlify](https://netlify.com) and sign in | ||
| 2. Create a new site (or use an existing one) | ||
| 3. Note down your **Site ID** from the site settings | ||
| 4. Generate a **Personal Access Token**: | ||
| - Go to User Settings → Applications → Personal access tokens | ||
| - Create a new token with appropriate permissions | ||
|
|
||
| ### 2. GitHub Secrets Configuration | ||
|
|
||
| Add the following secrets to your GitHub repository: | ||
|
|
||
| 1. Go to your repository → Settings → Secrets and variables → Actions | ||
| 2. Add these repository secrets: | ||
|
|
||
| - `NETLIFY_AUTH_TOKEN`: Your Netlify personal access token | ||
| - `NETLIFY_SITE_ID`: Your Netlify site ID | ||
|
|
||
| ### 3. Workflow Configuration | ||
|
|
||
| The deployment workflow is configured in `.github/workflows/deploy-docs.yml` and will: | ||
|
|
||
| - Trigger on pushes to `master` and `main` branches (production) | ||
| - Trigger on pull requests with the "docs" label (preview) | ||
| - Build documentation using `yarn docs` | ||
| - Deploy the generated docs to Netlify | ||
| - Add appropriate comments with deployment status | ||
|
|
||
| ### 4. Netlify Configuration | ||
|
|
||
| The `netlify.toml` file configures: | ||
| - Publish directory (`docs`) | ||
| - Redirect rules for better navigation | ||
| - Cache headers for static assets | ||
| - Security headers | ||
|
|
||
| ## Manual Deployment | ||
|
|
||
| You can manually trigger documentation deployment by: | ||
|
|
||
| 1. Going to Actions tab in your GitHub repository | ||
| 2. Selecting "Deploy Documentation to Netlify" workflow | ||
| 3. Clicking "Run workflow" | ||
|
|
||
| ## Local Documentation Development | ||
|
|
||
| To build documentation locally: | ||
|
|
||
| ```bash | ||
| # Install dependencies | ||
| yarn install | ||
|
|
||
| # Generate documentation | ||
| yarn docs | ||
|
|
||
| # View documentation (served from ./docs directory) | ||
| # You can use any static file server, for example: | ||
| npx serve docs | ||
| ``` | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| ### Common Issues | ||
|
|
||
| 1. **Build fails**: Check that all dependencies are installed and TypeDoc configuration is correct | ||
| 2. **Deployment fails**: Verify Netlify secrets are correctly set in GitHub repository settings | ||
| 3. **Missing documentation**: Ensure TypeDoc is properly configured in `typedoc.config.mjs` | ||
| 4. **Preview not deploying**: Make sure the "docs" label is added to the pull request | ||
|
|
||
| ### Checking Deployment Status | ||
|
|
||
| - View deployment logs in GitHub Actions | ||
| - Check Netlify dashboard for deployment status | ||
| - Review commit/PR comments for deployment notifications | ||
|
|
||
| ## Documentation Structure | ||
|
|
||
| The generated documentation includes: | ||
| - API reference for all exported functions and classes | ||
| - Type definitions and interfaces | ||
| - Coverage reports (if configured) | ||
| - Interactive navigation and search | ||
| - External links to React documentation | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| [build] | ||
| # This is the directory that will be deployed to Netlify | ||
| publish = "docs" | ||
|
|
||
| # Build command (not needed since we build in GitHub Actions) | ||
| command = "yarn docs" | ||
|
|
||
| [build.environment] | ||
| NODE_VERSION = "20" | ||
|
|
||
| # Redirect rules for better documentation navigation | ||
| [[redirects]] | ||
| from = "/" | ||
| to = "/index.html" | ||
| status = 200 | ||
|
|
||
| # Cache static assets | ||
| [[headers]] | ||
| for = "/*.js" | ||
| [headers.values] | ||
| Cache-Control = "public, max-age=31536000, immutable" | ||
|
|
||
| [[headers]] | ||
| for = "/*.css" | ||
| [headers.values] | ||
| Cache-Control = "public, max-age=31536000, immutable" | ||
|
|
||
| [[headers]] | ||
| for = "/*.png" | ||
| [headers.values] | ||
| Cache-Control = "public, max-age=31536000, immutable" | ||
|
|
||
| [[headers]] | ||
| for = "/*.svg" | ||
| [headers.values] | ||
| Cache-Control = "public, max-age=31536000, immutable" | ||
|
|
||
| # Security headers | ||
| [[headers]] | ||
| for = "/*" | ||
| [headers.values] | ||
| X-Frame-Options = "DENY" | ||
| X-XSS-Protection = "1; mode=block" | ||
| X-Content-Type-Options = "nosniff" | ||
| Referrer-Policy = "strict-origin-when-cross-origin" |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The workflow condition checks for 'documentation' label but the documentation mentions using 'docs' label. This mismatch will prevent preview deployments from triggering when users follow the documented instructions.
Copilot uses AI. Check for mistakes.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks like a valid suggestion