Skip to content

GitLab

Unverified Commit a8226eb0 authored by Neal Vaidya's avatar Neal Vaidya Committed by GitHub
Browse files

ci: add docs preview to PR CI (#6351) 


Signed-off-by: default avatarNeal Vaidya <nealv@nvidia.com>
parent 70822f35
Show whitespace changes
Inline Side-by-side
Showing with 103 additions and 54 deletions
.github/filters.yaml
View file @ a8226eb0
...@@ -19,6 +19,7 @@ all: ...@@ -19,6 +19,7 @@ all:
docs: docs:
- 'docs/**' - 'docs/**'
- 'fern/**' - 'fern/**'
- '.github/workflows/fern-docs.yml'
- '**/*.md' - '**/*.md'
- '**/*.txt' - '**/*.txt'
- '**/.gitignore' - '**/.gitignore'
......
.github/workflows/fern-docs.yml
View file @ a8226eb0
...@@ -18,18 +18,19 @@ ...@@ -18,18 +18,19 @@
# This workflow handles all Fern documentation automation: # This workflow handles all Fern documentation automation:
# #
# 1. LINT (PRs): Validates Fern configuration and checks for broken links # 1. LINT (PRs): Validates Fern configuration and checks for broken links
# - Triggers on pull requests when docs/** files change # - Triggers on PRs when docs/** files change
# - Runs `fern check` and `fern docs broken-links` # - Runs `fern check` and `fern docs broken-links`
# #
# 2. SYNC dev (push to main): Syncs docs/ from main to fern/ on docs-website branch # 2. SYNC & PUBLISH/PREVIEW: Syncs docs/ from source branch to fern/ on docs-website
# - Triggers on push to main when docs/** files change # - Triggers on push to main or PRs when docs/** files change
# - Preserves versioned documentation snapshots on docs-website branch # - On main: commits and pushes to docs-website, then publishes via `fern generate --docs`
# - Publishes docs to Fern after syncing # - On PRs: generates a preview URL via `fern generate --docs --preview` and comments on PR
# - Preserves versioned documentation (products[0]) from docs-website's docs.yml
# #
# 3. VERSION RELEASE (tags): Creates versioned documentation snapshot # 3. VERSION RELEASE (tags): Creates versioned documentation snapshot
# - Triggers on new version tags (vX.Y.Z format) # - Triggers on new version tags (vX.Y.Z format)
# - Creates pages-vX.Y.Z/ directory on docs-website branch # - Creates fern/pages-vX.Y.Z/ directory on docs-website branch
# - Updates docs.yml with new version entry # - Updates fern/docs.yml with new version entry
# - Publishes docs to Fern after releasing # - Publishes docs to Fern after releasing
# #
# Note: The publish step is included inline because pushes made with GITHUB_TOKEN # Note: The publish step is included inline because pushes made with GITHUB_TOKEN
...@@ -55,6 +56,7 @@ on: ...@@ -55,6 +56,7 @@ on:
permissions: permissions:
contents: write contents: write
pull-requests: write
jobs: jobs:
# Detect changed files for conditional job execution # Detect changed files for conditional job execution
...@@ -138,23 +140,33 @@ jobs: ...@@ -138,23 +140,33 @@ jobs:
run: fern docs broken-links run: fern docs broken-links
############################################################################# #############################################################################
# SYNC dev - Run on push to main when docs/** files change # SYNC & PUBLISH/PREVIEW - Syncs docs content to docs-website structure
# On main: commits, pushes, and publishes to Fern
# On PRs: generates a preview URL and comments on the PR
############################################################################# #############################################################################
sync-dev: preview-or-publish-docs:
name: Sync dev to docs-website name: Preview or publish docs
needs: changed-files needs: changed-files
if: | if: |
github.ref == 'refs/heads/main' && github.ref_type != 'tag' &&
(needs.changed-files.outputs.docs == 'true' || github.event_name == 'workflow_dispatch') && (needs.changed-files.outputs.docs == 'true' || github.event_name == 'workflow_dispatch') &&
(github.event.inputs.tag == '' || github.event.inputs.tag == null) (github.event.inputs.tag == '' || github.event.inputs.tag == null)
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- name: Checkout main branch - name: Determine context
id: ctx
run: |
if [ "$GITHUB_REF" = "refs/heads/main" ]; then
echo "is_main=true" >> $GITHUB_OUTPUT
else
echo "is_main=false" >> $GITHUB_OUTPUT
fi
- name: Checkout source branch
uses: actions/checkout@v4 uses: actions/checkout@v4
with: with:
ref: main path: source-checkout
path: main-checkout
fetch-depth: 1 fetch-depth: 1
- name: Checkout docs-website branch - name: Checkout docs-website branch
...@@ -164,54 +176,47 @@ jobs: ...@@ -164,54 +176,47 @@ jobs:
path: docs-checkout path: docs-checkout
fetch-depth: 1 fetch-depth: 1
token: ${{ secrets.GITHUB_TOKEN }} token: ${{ secrets.GITHUB_TOKEN }}
- name: Setup Git
run: |
cd docs-checkout
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
- name: Sync dev content from main - name: Sync dev content from main
run: | run: |
# Sync pages/ directory (dev content) # Sync pages/ directory (dev content)
echo "Syncing pages/ from main to docs-website branch..." echo "Syncing pages/ to docs-website branch..."
rm -rf docs-checkout/fern/pages rm -rf docs-checkout/fern/pages
cp -r main-checkout/docs/pages docs-checkout/fern/pages cp -r source-checkout/docs/pages docs-checkout/fern/pages
# Sync versions/dev.yml (dev navigation) # Sync versions/dev.yml (dev navigation)
echo "Syncing versions/dev.yml from main to docs-website branch..." echo "Syncing versions/dev.yml to docs-website branch..."
cp main-checkout/docs/versions/dev.yml docs-checkout/fern/versions/dev.yml cp source-checkout/docs/versions/dev.yml docs-checkout/fern/versions/dev.yml
# Sync assets/ directory # Sync assets/ directory
echo "Syncing assets/ from main to docs-website branch..." echo "Syncing assets/ to docs-website branch..."
rm -rf docs-checkout/fern/assets rm -rf docs-checkout/fern/assets
cp -r main-checkout/docs/assets docs-checkout/fern/assets cp -r source-checkout/docs/assets docs-checkout/fern/assets
# Sync fern.config.json # Sync fern.config.json
echo "Syncing fern.config.json from main to docs-website branch..." echo "Syncing fern.config.json to docs-website branch..."
cp main-checkout/docs/fern.config.json docs-checkout/fern/fern.config.json cp source-checkout/docs/fern.config.json docs-checkout/fern/fern.config.json
# Sync .gitignore if it exists # Sync .gitignore if it exists
if [ -f main-checkout/docs/.gitignore ]; then if [ -f source-checkout/docs/.gitignore ]; then
cp main-checkout/docs/.gitignore docs-checkout/fern/.gitignore cp source-checkout/docs/.gitignore docs-checkout/fern/.gitignore
fi fi
# Sync convert_callouts.py script # Sync convert_callouts.py script
if [ -f main-checkout/docs/convert_callouts.py ]; then if [ -f source-checkout/docs/convert_callouts.py ]; then
cp main-checkout/docs/convert_callouts.py docs-checkout/fern/convert_callouts.py cp source-checkout/docs/convert_callouts.py docs-checkout/fern/convert_callouts.py
fi fi
# Sync components/ directory (e.g., CustomFooter.tsx) # Sync components/ directory (e.g., CustomFooter.tsx)
if [ -d main-checkout/docs/components ]; then if [ -d source-checkout/docs/components ]; then
echo "Syncing components/ from main to docs-website branch..." echo "Syncing components/ to docs-website branch..."
rm -rf docs-checkout/fern/components rm -rf docs-checkout/fern/components
cp -r main-checkout/docs/components docs-checkout/fern/components cp -r source-checkout/docs/components docs-checkout/fern/components
fi fi
# Sync main.css # Sync main.css
if [ -f main-checkout/docs/main.css ]; then if [ -f source-checkout/docs/main.css ]; then
echo "Syncing main.css from main to docs-website branch..." echo "Syncing main.css to docs-website branch..."
cp main-checkout/docs/main.css docs-checkout/fern/main.css cp source-checkout/docs/main.css docs-checkout/fern/main.css
fi fi
- name: Convert GitHub callouts to Fern format - name: Convert GitHub callouts to Fern format
...@@ -230,8 +235,8 @@ jobs: ...@@ -230,8 +235,8 @@ jobs:
echo "Preserved products[0] block:" echo "Preserved products[0] block:"
cat /tmp/preserved_product.yml cat /tmp/preserved_product.yml
# Copy docs.yml from main to get config updates (redirects, layout, etc.) # Copy docs.yml from source to get config updates (redirects, layout, etc.)
cp ../../main-checkout/docs/docs.yml docs.yml cp ../../source-checkout/docs/docs.yml docs.yml
# Restore the preserved products[0] block # Restore the preserved products[0] block
yq -i '.products[0] = load("/tmp/preserved_product.yml")' docs.yml yq -i '.products[0] = load("/tmp/preserved_product.yml")' docs.yml
...@@ -252,8 +257,61 @@ jobs: ...@@ -252,8 +257,61 @@ jobs:
git status --short git status --short
fi fi
- name: Commit and push changes - name: Setup Node.js
if: steps.changes.outputs.has_changes == 'true'
uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install Fern CLI
if: steps.changes.outputs.has_changes == 'true' if: steps.changes.outputs.has_changes == 'true'
run: npm install -g fern-api
##########################################################################
# PREVIEW - Generate a preview URL for docs changes
##########################################################################
- name: Generate docs preview
if: steps.ctx.outputs.is_main != 'true' && steps.changes.outputs.has_changes == 'true'
id: preview
working-directory: docs-checkout/fern
env:
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
run: |
OUTPUT=$(fern generate --docs --preview 2>&1)
FERN_EXIT=$?
echo "$OUTPUT"
if [ $FERN_EXIT -ne 0 ]; then
echo "::warning::Fern docs preview generation failed (exit $FERN_EXIT)"
fi
URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K\S+') || true
if [ -n "$URL" ]; then
echo "url=$URL" >> $GITHUB_OUTPUT
fi
- name: Comment preview URL on PR
if: steps.ctx.outputs.is_main != 'true' && steps.preview.outputs.url != '' && startsWith(github.ref, 'refs/heads/pull-request/')
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
PR_NUM="${GITHUB_REF##*/}"
gh pr comment "https://github.com/${{ github.repository }}/pull/${PR_NUM}" \
--edit-last --create-if-none \
--body "🌿 **Fern Docs Preview:** ${{ steps.preview.outputs.url }}/dev"
##########################################################################
# PUSH AND PUBLISH - push changes to docs-website branch and publish docs
##########################################################################
- name: Setup Git
if: steps.ctx.outputs.is_main == 'true' && steps.changes.outputs.has_changes == 'true'
run: |
cd docs-checkout
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
- name: Commit and push changes
if: steps.ctx.outputs.is_main == 'true' && steps.changes.outputs.has_changes == 'true'
run: | run: |
cd docs-checkout cd docs-checkout
...@@ -269,18 +327,8 @@ jobs: ...@@ -269,18 +327,8 @@ jobs:
echo "Successfully synced dev docs to docs-website branch" echo "Successfully synced dev docs to docs-website branch"
- name: Setup Node.js
if: steps.changes.outputs.has_changes == 'true'
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install Fern CLI
if: steps.changes.outputs.has_changes == 'true'
run: npm install -g fern-api
- name: Publish Docs - name: Publish Docs
if: steps.changes.outputs.has_changes == 'true' if: steps.ctx.outputs.is_main == 'true' && steps.changes.outputs.has_changes == 'true'
env: env:
FERN_TOKEN: ${{ secrets.FERN_TOKEN }} FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
working-directory: docs-checkout/fern working-directory: docs-checkout/fern
...@@ -472,7 +520,7 @@ jobs: ...@@ -472,7 +520,7 @@ jobs:
- name: Setup Node.js - name: Setup Node.js
uses: actions/setup-node@v4 uses: actions/setup-node@v4
with: with:
node-version: '20' node-version: '22'
- name: Install Fern CLI - name: Install Fern CLI
run: npm install -g fern-api run: npm install -g fern-api
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment