From 1087275f219d6e3ac65575b12b74122669f4cbff Mon Sep 17 00:00:00 2001 From: Loren Posen Date: Fri, 10 Oct 2025 09:42:07 -0700 Subject: [PATCH 1/6] chore: add Netlify configuration and deployment workflow for documentation --- .github/workflows/deploy-docs.yml | 38 ++++++++++++++++++++++++++ .gitignore | 3 +++ netlify.toml | 45 +++++++++++++++++++++++++++++++ 3 files changed, 86 insertions(+) create mode 100644 .github/workflows/deploy-docs.yml create mode 100644 netlify.toml diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 000000000..8edddff1f --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,38 @@ +name: Deploy Documentation to Netlify + +on: + push: + branches: + - master + - main + workflow_dispatch: # Allow manual triggering + +jobs: + deploy-docs: + runs-on: ubuntu-latest + + 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: Deploy to Netlify + uses: nwtgck/actions-netlify@v3.0 + with: + publish-dir: "./docs" + production-branch: master + github-token: ${{ secrets.GITHUB_TOKEN }} + deploy-message: "Deploy docs from commit ${{ github.sha }}" + enable-pull-request-comment: false + enable-commit-comment: true + overwrites-pull-request-comment: true + env: + NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} + NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }} diff --git a/.gitignore b/.gitignore index 8d348ce59..356417c19 100644 --- a/.gitignore +++ b/.gitignore @@ -89,3 +89,6 @@ android/generated .xcode.env.local coverage/ docs/ + +# Local Netlify folder +.netlify diff --git a/netlify.toml b/netlify.toml new file mode 100644 index 000000000..8f8265b78 --- /dev/null +++ b/netlify.toml @@ -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" From a8d1d94be5fe2abd92ed1cd226458bd49af76b22 Mon Sep 17 00:00:00 2001 From: Loren Posen Date: Fri, 10 Oct 2025 09:45:19 -0700 Subject: [PATCH 2/6] docs: update README to enhance API documentation section and rename sample projects --- README.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index dd3918d21..c656b6790 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ This SDK helps you integrate your React Native-based iOS and Android apps with Iterable. It supports JavaScript and TypeScript. + @@ -20,7 +21,8 @@ Iterable. It supports JavaScript and TypeScript. - [Architecture Support](#architecture-support) - [Installation](#installation) - [Features](#features) - - [Sample projects](#sample-projects) + - [📚 API Documentation](#-api-documentation) + - [Example project](#example-project) - [Version mapping](#version-mapping) - [Release notes, support and troubleshooting](#release-notes-support-and-troubleshooting) - [License](#license) @@ -79,7 +81,11 @@ To learn more about the SDK, read: - [In-App Messages](https://support.iterable.com/hc/articles/360045714172) - [Migrating to Iterable's React Native SDK](https://support.iterable.com/hc/articles/360046134931) -## Sample projects +## 📚 API Documentation + +View the complete API documentation at [https://iterable-react-native-sdk.netlify.app](https://iterable-react-native-sdk.netlify.app) + +## Example project For sample code, take a look at the following project: From 05825c525c26cd9ebe65034af23f0a61b25475f1 Mon Sep 17 00:00:00 2001 From: Loren Posen Date: Fri, 10 Oct 2025 10:07:30 -0700 Subject: [PATCH 3/6] docs: add documentation deployment setup for Netlify with GitHub Actions --- .github/workflows/deploy-docs.yml | 47 +++++++++++- README.md | 20 ++--- docs-deployment.md | 120 ++++++++++++++++++++++++++++++ 3 files changed, 174 insertions(+), 13 deletions(-) create mode 100644 docs-deployment.md diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 8edddff1f..446ab9bd9 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -5,11 +5,18 @@ on: branches: - master - main + pull_request: + types: [opened, synchronize, labeled, unlabeled] workflow_dispatch: # Allow manual triggering jobs: deploy-docs: runs-on: ubuntu-latest + # Only run on master/main pushes or PRs with "docs" 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, 'docs') || + github.event_name == 'workflow_dispatch' steps: - name: Checkout code @@ -23,15 +30,49 @@ jobs: - name: Build documentation run: yarn docs - - name: Deploy to Netlify + - 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@v3.0 with: publish-dir: "./docs" production-branch: master github-token: ${{ secrets.GITHUB_TOKEN }} - deploy-message: "Deploy docs from commit ${{ github.sha }}" - enable-pull-request-comment: false + 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@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 }} diff --git a/README.md b/README.md index c656b6790..fb5a88a63 100644 --- a/README.md +++ b/README.md @@ -18,10 +18,10 @@ Iterable. It supports JavaScript and TypeScript. - [Iterable's React Native SDK](#iterables-react-native-sdk) - [Requirements](#requirements) - - [Architecture Support](#architecture-support) - [Installation](#installation) - - [Features](#features) - [📚 API Documentation](#-api-documentation) + - [Architecture Support](#architecture-support) + - [Features](#features) - [Example project](#example-project) - [Version mapping](#version-mapping) - [Release notes, support and troubleshooting](#release-notes-support-and-troubleshooting) @@ -55,6 +55,14 @@ Iterable's React Native SDK relies on: - [`minSdkVersion` 21+, `compileSdkVersion` 31+](https://medium.com/androiddevelopers/picking-your-compilesdkversion-minsdkversion-targetsdkversion-a098a0341ebd) - [Iterable's Android SDK](https://github.com/Iterable/iterable-android-sdk) +## Installation + +For installation instructions, read [Installing Iterable's React Native SDK](https://support.iterable.com/hc/articles/360045714132). + +## 📚 API Documentation + +View the [API documentation](https://iterable-react-native-sdk.netlify.app). + ## Architecture Support **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 Architecture, and suggest using the legacy architecture in the meantime. *TLDR;* Use the New Architecture at your own risk -- you may encounter significant issues. -## Installation - -For installation instructions, read [Installing Iterable's React Native SDK](https://support.iterable.com/hc/articles/360045714132). - ## Features To learn more about the SDK, read: @@ -81,10 +85,6 @@ To learn more about the SDK, read: - [In-App Messages](https://support.iterable.com/hc/articles/360045714172) - [Migrating to Iterable's React Native SDK](https://support.iterable.com/hc/articles/360046134931) -## 📚 API Documentation - -View the complete API documentation at [https://iterable-react-native-sdk.netlify.app](https://iterable-react-native-sdk.netlify.app) - ## Example project For sample code, take a look at the following project: diff --git a/docs-deployment.md b/docs-deployment.md new file mode 100644 index 000000000..fa5a0d69b --- /dev/null +++ b/docs-deployment.md @@ -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 From 4aa850082fde6d1fa7fa57ae42c8c244c59bbf33 Mon Sep 17 00:00:00 2001 From: Loren Posen Date: Fri, 10 Oct 2025 10:11:23 -0700 Subject: [PATCH 4/6] fix: update label from 'docs' to 'documentation' in deployment workflow for clarity --- .github/workflows/deploy-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 446ab9bd9..708622e56 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -15,7 +15,7 @@ jobs: # Only run on master/main pushes or PRs with "docs" 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, 'docs') || + github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'documentation') || github.event_name == 'workflow_dispatch' steps: From 2ce01cd5625eb6faa9e92d86731bcca45ea96e64 Mon Sep 17 00:00:00 2001 From: Loren Posen Date: Fri, 10 Oct 2025 10:13:24 -0700 Subject: [PATCH 5/6] chore: update permissions in deployment workflow for documentation and clarify label usage --- .github/workflows/deploy-docs.yml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 708622e56..aa296843e 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -12,7 +12,11 @@ on: jobs: deploy-docs: runs-on: ubuntu-latest - # Only run on master/main pushes or PRs with "docs" label + 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') || From c361895ac9fd1ea6a05563e7fc8cc31358578e7a Mon Sep 17 00:00:00 2001 From: Loren Posen Date: Fri, 10 Oct 2025 10:19:56 -0700 Subject: [PATCH 6/6] chore: update Netlify action version in deployment workflow for consistency --- .github/workflows/deploy-docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index aa296843e..366cae0c9 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -56,7 +56,7 @@ jobs: - name: Deploy to Netlify (Production) if: github.event_name == 'push' - uses: nwtgck/actions-netlify@v3.0 + uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654 with: publish-dir: "./docs" production-branch: master @@ -69,7 +69,7 @@ jobs: - name: Deploy to Netlify (Preview) if: github.event_name == 'pull_request' - uses: nwtgck/actions-netlify@v3.0 + uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654 # v3.0 with: publish-dir: "./docs" production-branch: master