Skip to content

Commit 8d34f62

Browse files
lposenlposen
authored
Merge pull request #736 from Iterable/MOB-12295-publish-docs-to-netlify
[MOB-12295] publish docs to netlify
2 parents b1decd7 + c361895 commit 8d34f62

File tree

5 files changed

+264
-7
lines changed

5 files changed

+264
-7
lines changed

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

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
name: Deploy Documentation to Netlify
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
- main
8+
pull_request:
9+
types: [opened, synchronize, labeled, unlabeled]
10+
workflow_dispatch: # Allow manual triggering
11+
12+
jobs:
13+
deploy-docs:
14+
runs-on: ubuntu-latest
15+
permissions:
16+
contents: read
17+
pull-requests: write
18+
issues: write
19+
# Only run on master/main pushes or PRs with "documentation" label
20+
if: |
21+
github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main') ||
22+
github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'documentation') ||
23+
github.event_name == 'workflow_dispatch'
24+
25+
steps:
26+
- name: Checkout code
27+
uses: actions/checkout@v4
28+
with:
29+
fetch-depth: 0 # Fetch full history for proper git info
30+
31+
- name: Setup
32+
uses: ./.github/actions/setup
33+
34+
- name: Build documentation
35+
run: yarn docs
36+
37+
- name: Determine deployment type
38+
id: deployment-type
39+
run: |
40+
if [[ "${{ github.event_name }}" == "push" ]]; then
41+
echo "type=production" >> $GITHUB_OUTPUT
42+
echo "message=Deploying to production site" >> $GITHUB_OUTPUT
43+
else
44+
echo "type=preview" >> $GITHUB_OUTPUT
45+
echo "message=Deploying preview for PR #${{ github.event.number }}" >> $GITHUB_OUTPUT
46+
fi
47+
48+
- name: Show deployment info
49+
run: |
50+
echo "🚀 ${{ steps.deployment-type.outputs.message }}"
51+
echo "Branch: ${{ github.ref_name }}"
52+
echo "Commit: ${{ github.sha }}"
53+
if [[ "${{ github.event_name }}" == "pull_request" ]]; then
54+
echo "Deployment alias: ${{ github.head_ref }}"
55+
fi
56+
57+
- name: Deploy to Netlify (Production)
58+
if: github.event_name == 'push'
59+
uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654
60+
with:
61+
publish-dir: "./docs"
62+
production-branch: master
63+
github-token: ${{ secrets.GITHUB_TOKEN }}
64+
deploy-message: "${{ steps.deployment-type.outputs.message }}"
65+
enable-commit-comment: true
66+
env:
67+
NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
68+
NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
69+
70+
- name: Deploy to Netlify (Preview)
71+
if: github.event_name == 'pull_request'
72+
uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654 # v3.0
73+
with:
74+
publish-dir: "./docs"
75+
production-branch: master
76+
github-token: ${{ secrets.GITHUB_TOKEN }}
77+
deploy-message: "${{ steps.deployment-type.outputs.message }}"
78+
alias: ${{ github.head_ref }}
79+
enable-pull-request-comment: true
80+
overwrites-pull-request-comment: true
81+
env:
82+
NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
83+
NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,3 +89,6 @@ android/generated
8989
.xcode.env.local
9090
coverage/
9191
docs/
92+
93+
# Local Netlify folder
94+
.netlify

‎README.md‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -11,16 +11,18 @@ This SDK helps you integrate your React Native-based iOS and Android apps with
1111
Iterable. It supports JavaScript and TypeScript.
1212

1313

14+
1415
<!-- @import "[TOC]" {cmd="toc" depthFrom=2 depthTo=6 orderedList=false} -->
1516

1617
<!-- code_chunk_output -->
1718

1819
- [Iterable's React Native SDK](#iterables-react-native-sdk)
1920
- [Requirements](#requirements)
20-
- [Architecture Support](#architecture-support)
2121
- [Installation](#installation)
22+
- [📚 API Documentation](#-api-documentation)
23+
- [Architecture Support](#architecture-support)
2224
- [Features](#features)
23-
- [Sample projects](#sample-projects)
25+
- [Example project](#example-project)
2426
- [Version mapping](#version-mapping)
2527
- [Release notes, support and troubleshooting](#release-notes-support-and-troubleshooting)
2628
- [License](#license)
@@ -53,6 +55,14 @@ Iterable's React Native SDK relies on:
5355
- [`minSdkVersion` 21+, `compileSdkVersion` 31+](https://medium.com/androiddevelopers/picking-your-compilesdkversion-minsdkversion-targetsdkversion-a098a0341ebd)
5456
- [Iterable's Android SDK](https://github.com/Iterable/iterable-android-sdk)
5557

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+
5666
## Architecture Support
5767

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

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

7076
To learn more about the SDK, read:
@@ -79,7 +85,7 @@ To learn more about the SDK, read:
7985
- [In-App Messages](https://support.iterable.com/hc/articles/360045714172)
8086
- [Migrating to Iterable's React Native SDK](https://support.iterable.com/hc/articles/360046134931)
8187

82-
## Sample projects
88+
## Example project
8389

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

‎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

‎netlify.toml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
[build]
2+
# This is the directory that will be deployed to Netlify
3+
publish = "docs"
4+
5+
# Build command (not needed since we build in GitHub Actions)
6+
command = "yarn docs"
7+
8+
[build.environment]
9+
NODE_VERSION = "20"
10+
11+
# Redirect rules for better documentation navigation
12+
[[redirects]]
13+
from = "/"
14+
to = "/index.html"
15+
status = 200
16+
17+
# Cache static assets
18+
[[headers]]
19+
for = "/*.js"
20+
[headers.values]
21+
Cache-Control = "public, max-age=31536000, immutable"
22+
23+
[[headers]]
24+
for = "/*.css"
25+
[headers.values]
26+
Cache-Control = "public, max-age=31536000, immutable"
27+
28+
[[headers]]
29+
for = "/*.png"
30+
[headers.values]
31+
Cache-Control = "public, max-age=31536000, immutable"
32+
33+
[[headers]]
34+
for = "/*.svg"
35+
[headers.values]
36+
Cache-Control = "public, max-age=31536000, immutable"
37+
38+
# Security headers
39+
[[headers]]
40+
for = "/*"
41+
[headers.values]
42+
X-Frame-Options = "DENY"
43+
X-XSS-Protection = "1; mode=block"
44+
X-Content-Type-Options = "nosniff"
45+
Referrer-Policy = "strict-origin-when-cross-origin"

0 commit comments

Comments
 (0)