diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 000000000..366cae0c9 --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -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 }} 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/README.md b/README.md index dd3918d21..fb5a88a63 100644 --- a/README.md +++ b/README.md @@ -11,16 +11,18 @@ This SDK helps you integrate your React Native-based iOS and Android apps with Iterable. It supports JavaScript and TypeScript. + - [Iterable's React Native SDK](#iterables-react-native-sdk) - [Requirements](#requirements) - - [Architecture Support](#architecture-support) - [Installation](#installation) + - [📚 API Documentation](#-api-documentation) + - [Architecture Support](#architecture-support) - [Features](#features) - - [Sample projects](#sample-projects) + - [Example project](#example-project) - [Version mapping](#version-mapping) - [Release notes, support and troubleshooting](#release-notes-support-and-troubleshooting) - [License](#license) @@ -53,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 @@ -61,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: @@ -79,7 +85,7 @@ 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 +## 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 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"