Skip to content

Commit 05825c5

Browse files
lposenlposen
committed
docs: add documentation deployment setup for Netlify with GitHub Actions
1 parent a8d1d94 commit 05825c5

File tree

3 files changed

+174
-13
lines changed

3 files changed

+174
-13
lines changed

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

Lines changed: 44 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,18 @@ on:
55
branches:
66
- master
77
- main
8+
pull_request:
9+
types: [opened, synchronize, labeled, unlabeled]
810
workflow_dispatch: # Allow manual triggering
911

1012
jobs:
1113
deploy-docs:
1214
runs-on: ubuntu-latest
15+
# Only run on master/main pushes or PRs with "docs" label
16+
if: |
17+
github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main') ||
18+
github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'docs') ||
19+
github.event_name == 'workflow_dispatch'
1320
1421
steps:
1522
- name: Checkout code
@@ -23,15 +30,49 @@ jobs:
2330
- name: Build documentation
2431
run: yarn docs
2532

26-
- name: Deploy to Netlify
33+
- name: Determine deployment type
34+
id: deployment-type
35+
run: |
36+
if [[ "${{ github.event_name }}" == "push" ]]; then
37+
echo "type=production" >> $GITHUB_OUTPUT
38+
echo "message=Deploying to production site" >> $GITHUB_OUTPUT
39+
else
40+
echo "type=preview" >> $GITHUB_OUTPUT
41+
echo "message=Deploying preview for PR #${{ github.event.number }}" >> $GITHUB_OUTPUT
42+
fi
43+
44+
- name: Show deployment info
45+
run: |
46+
echo "🚀 ${{ steps.deployment-type.outputs.message }}"
47+
echo "Branch: ${{ github.ref_name }}"
48+
echo "Commit: ${{ github.sha }}"
49+
if [[ "${{ github.event_name }}" == "pull_request" ]]; then
50+
echo "Deployment alias: ${{ github.head_ref }}"
51+
fi
52+
53+
- name: Deploy to Netlify (Production)
54+
if: github.event_name == 'push'
2755
uses: nwtgck/actions-netlify@v3.0
2856
with:
2957
publish-dir: "./docs"
3058
production-branch: master
3159
github-token: ${{ secrets.GITHUB_TOKEN }}
32-
deploy-message: "Deploy docs from commit ${{ github.sha }}"
33-
enable-pull-request-comment: false
60+
deploy-message: "${{ steps.deployment-type.outputs.message }}"
3461
enable-commit-comment: true
62+
env:
63+
NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
64+
NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
65+
66+
- name: Deploy to Netlify (Preview)
67+
if: github.event_name == 'pull_request'
68+
uses: nwtgck/actions-netlify@v3.0
69+
with:
70+
publish-dir: "./docs"
71+
production-branch: master
72+
github-token: ${{ secrets.GITHUB_TOKEN }}
73+
deploy-message: "${{ steps.deployment-type.outputs.message }}"
74+
alias: ${{ github.head_ref }}
75+
enable-pull-request-comment: true
3576
overwrites-pull-request-comment: true
3677
env:
3778
NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}

‎README.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,10 @@ Iterable. It supports JavaScript and TypeScript.
1818

1919
- [Iterable's React Native SDK](#iterables-react-native-sdk)
2020
- [Requirements](#requirements)
21-
- [Architecture Support](#architecture-support)
2221
- [Installation](#installation)
23-
- [Features](#features)
2422
- [📚 API Documentation](#-api-documentation)
23+
- [Architecture Support](#architecture-support)
24+
- [Features](#features)
2525
- [Example project](#example-project)
2626
- [Version mapping](#version-mapping)
2727
- [Release notes, support and troubleshooting](#release-notes-support-and-troubleshooting)
@@ -55,6 +55,14 @@ Iterable's React Native SDK relies on:
5555
- [`minSdkVersion` 21+, `compileSdkVersion` 31+](https://medium.com/androiddevelopers/picking-your-compilesdkversion-minsdkversion-targetsdkversion-a098a0341ebd)
5656
- [Iterable's Android SDK](https://github.com/Iterable/iterable-android-sdk)
5757

58+
## Installation
59+
60+
For installation instructions, read [Installing Iterable's React Native SDK](https://support.iterable.com/hc/articles/360045714132).
61+
62+
## 📚 API Documentation
63+
64+
View the [API documentation](https://iterable-react-native-sdk.netlify.app).
65+
5866
## Architecture Support
5967

6068
**Important**: Iterable's React Native SDK has limited support for [React
@@ -63,10 +71,6 @@ through interop. We are in the process of updating the SDK to fully support the
6371
Architecture, and suggest using the legacy architecture in the meantime. *TLDR;* Use the New Architecture at your own risk --
6472
you may encounter significant issues.
6573

66-
## Installation
67-
68-
For installation instructions, read [Installing Iterable's React Native SDK](https://support.iterable.com/hc/articles/360045714132).
69-
7074
## Features
7175

7276
To learn more about the SDK, read:
@@ -81,10 +85,6 @@ To learn more about the SDK, read:
8185
- [In-App Messages](https://support.iterable.com/hc/articles/360045714172)
8286
- [Migrating to Iterable's React Native SDK](https://support.iterable.com/hc/articles/360046134931)
8387

84-
## 📚 API Documentation
85-
86-
View the complete API documentation at [https://iterable-react-native-sdk.netlify.app](https://iterable-react-native-sdk.netlify.app)
87-
8888
## Example project
8989

9090
For sample code, take a look at the following project:

‎docs-deployment.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Documentation Deployment Setup
2+
3+
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.
4+
5+
## Overview
6+
7+
The project uses GitHub Actions to automatically build and deploy documentation to Netlify in two scenarios:
8+
9+
1. **Production Deployment**: When changes are merged to the master branch
10+
2. **Preview Deployment**: When a pull request has the "docs" label
11+
12+
The documentation is generated using TypeDoc and includes API documentation, coverage reports, and interactive navigation.
13+
14+
## Deployment Triggers
15+
16+
### Production Deployment
17+
- Automatically triggers on pushes to `master` or `main` branches
18+
- Deploys to the production Netlify site
19+
- Updates the main documentation URL
20+
21+
### Preview Deployment
22+
- Triggers on pull requests with the "docs" label
23+
- Creates a preview deployment for testing documentation changes
24+
- Adds a comment to the PR with the preview URL
25+
- Perfect for reviewing documentation changes before merging
26+
27+
## How to Use Preview Deployments
28+
29+
1. Create a pull request with documentation changes
30+
2. Add the "docs" label to the pull request
31+
3. The workflow will automatically build and deploy a preview
32+
4. Check the PR comments for the preview URL
33+
5. Review the changes and merge when ready
34+
35+
## Setup Instructions
36+
37+
### 1. Netlify Setup
38+
39+
1. Go to [Netlify](https://netlify.com) and sign in
40+
2. Create a new site (or use an existing one)
41+
3. Note down your **Site ID** from the site settings
42+
4. Generate a **Personal Access Token**:
43+
- Go to User Settings → Applications → Personal access tokens
44+
- Create a new token with appropriate permissions
45+
46+
### 2. GitHub Secrets Configuration
47+
48+
Add the following secrets to your GitHub repository:
49+
50+
1. Go to your repository → Settings → Secrets and variables → Actions
51+
2. Add these repository secrets:
52+
53+
- `NETLIFY_AUTH_TOKEN`: Your Netlify personal access token
54+
- `NETLIFY_SITE_ID`: Your Netlify site ID
55+
56+
### 3. Workflow Configuration
57+
58+
The deployment workflow is configured in `.github/workflows/deploy-docs.yml` and will:
59+
60+
- Trigger on pushes to `master` and `main` branches (production)
61+
- Trigger on pull requests with the "docs" label (preview)
62+
- Build documentation using `yarn docs`
63+
- Deploy the generated docs to Netlify
64+
- Add appropriate comments with deployment status
65+
66+
### 4. Netlify Configuration
67+
68+
The `netlify.toml` file configures:
69+
- Publish directory (`docs`)
70+
- Redirect rules for better navigation
71+
- Cache headers for static assets
72+
- Security headers
73+
74+
## Manual Deployment
75+
76+
You can manually trigger documentation deployment by:
77+
78+
1. Going to Actions tab in your GitHub repository
79+
2. Selecting "Deploy Documentation to Netlify" workflow
80+
3. Clicking "Run workflow"
81+
82+
## Local Documentation Development
83+
84+
To build documentation locally:
85+
86+
```bash
87+
# Install dependencies
88+
yarn install
89+
90+
# Generate documentation
91+
yarn docs
92+
93+
# View documentation (served from ./docs directory)
94+
# You can use any static file server, for example:
95+
npx serve docs
96+
```
97+
98+
## Troubleshooting
99+
100+
### Common Issues
101+
102+
1. **Build fails**: Check that all dependencies are installed and TypeDoc configuration is correct
103+
2. **Deployment fails**: Verify Netlify secrets are correctly set in GitHub repository settings
104+
3. **Missing documentation**: Ensure TypeDoc is properly configured in `typedoc.config.mjs`
105+
4. **Preview not deploying**: Make sure the "docs" label is added to the pull request
106+
107+
### Checking Deployment Status
108+
109+
- View deployment logs in GitHub Actions
110+
- Check Netlify dashboard for deployment status
111+
- Review commit/PR comments for deployment notifications
112+
113+
## Documentation Structure
114+
115+
The generated documentation includes:
116+
- API reference for all exported functions and classes
117+
- Type definitions and interfaces
118+
- Coverage reports (if configured)
119+
- Interactive navigation and search
120+
- External links to React documentation

0 commit comments

Comments
 (0)