Skip to content

Commit a964c48

Browse files
ArekBalysNordicArekBalysNordic
committed
workflows: Fix doc preview workflow
Changed a way to store DOC preview on github pages. Signed-off-by: Arkadiusz Balys <arkadiusz.balys@nordicsemi.no>
1 parent dcc174f commit a964c48

10 files changed

Lines changed: 483 additions & 253 deletions

File tree

‎.github/actions/deploy-docs-preview/action.yml‎

Lines changed: 42 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,77 +1,61 @@
1-
# This GitHub Action deploys documentation previews for pull requests to the gh-pages branch.
1+
# This GitHub Action prepares documentation for deployment to GitHub Pages.
22
#
3-
# When triggered during a PR build, it uploads the built documentation from the specified directory
4-
# to a unique subdirectory (pr-preview/pr-<PR_NUMBER>) under the gh-pages branch.
5-
# This allows contributors and reviewers to view preview documentation for the PR without merging it.
6-
# The deployment is performed using the provided GitHub token for authentication, and is safe to run
7-
# concurrently for multiple PRs. If the gh-pages branch does not exist, it is initialized automatically.
83

9-
name: 'Deploy Docs Preview'
10-
description: 'Deploy documentation preview to gh-pages branch'
4+
name: 'Prepare Docs for Pages'
5+
description: 'Prepare documentation for GitHub Pages deployment'
116

127
inputs:
13-
github_token:
14-
description: 'GitHub token for authentication'
8+
docs_dir:
9+
description: 'Path to the directory containing built documentation'
1510
required: true
16-
repository:
17-
description: 'Repository in owner/repo format'
11+
target_path:
12+
description: 'Target path within the site (e.g., "pr-preview/pr-123" or "latest")'
1813
required: true
19-
pr_number:
20-
description: 'Pull request number'
21-
required: true
22-
commit_sha:
23-
description: 'Commit SHA for the PR head'
24-
required: true
25-
docs_build_dir:
26-
description: 'Path to the built documentation'
14+
existing_pages_dir:
15+
description: 'Path to existing site content'
16+
required: false
17+
default: '_existing_pages'
18+
output_dir:
19+
description: 'Output directory for the prepared site'
2720
required: false
28-
default: 'docs/_build_sphinx/html'
21+
default: '_site'
22+
23+
outputs:
24+
site_dir:
25+
description: 'Path to the prepared site directory'
26+
value: ${{ steps.prepare.outputs.site_dir }}
2927

3028
runs:
3129
using: 'composite'
3230
steps:
33-
- name: Deploy to gh-pages branch
31+
- name: Prepare site directory
32+
id: prepare
3433
shell: bash
3534
env:
36-
GITHUB_TOKEN: ${{ inputs.github_token }}
37-
REPOSITORY: ${{ inputs.repository }}
38-
PR_NUMBER: ${{ inputs.pr_number }}
39-
COMMIT_SHA: ${{ inputs.commit_sha }}
40-
DOCS_BUILD_DIR: ${{ inputs.docs_build_dir }}
35+
DOCS_DIR: ${{ inputs.docs_dir }}
36+
TARGET_PATH: ${{ inputs.target_path }}
37+
EXISTING_DIR: ${{ inputs.existing_pages_dir }}
38+
OUTPUT_DIR: ${{ inputs.output_dir }}
4139
run: |
42-
# Configure git
43-
git config --global user.name "github-actions[bot]"
44-
git config --global user.email "github-actions[bot]@users.noreply.github.com"
45-
46-
# Create a temporary directory for gh-pages content
47-
TEMP_DIR=$(mktemp -d)
48-
49-
# Clone just the gh-pages branch (or create it if it doesn't exist)
50-
if git ls-remote --exit-code --heads "https://x-access-token:${GITHUB_TOKEN}@github.com/${REPOSITORY}.git" gh-pages > /dev/null 2>&1; then
51-
git clone --single-branch --branch gh-pages --depth 1 "https://x-access-token:${GITHUB_TOKEN}@github.com/${REPOSITORY}.git" "$TEMP_DIR"
52-
else
53-
mkdir -p "$TEMP_DIR"
54-
cd "$TEMP_DIR"
55-
git init
56-
git remote add origin "https://x-access-token:${GITHUB_TOKEN}@github.com/${REPOSITORY}.git"
57-
git checkout -b gh-pages
58-
touch .nojekyll
59-
git add .nojekyll
60-
git commit -m "Initialize gh-pages branch"
40+
# Create output directory
41+
mkdir -p "${OUTPUT_DIR}"
42+
43+
# Copy existing pages content if available (preserves other PR previews)
44+
if [ -d "${EXISTING_DIR}" ] && [ "$(ls -A ${EXISTING_DIR} 2>/dev/null)" ]; then
45+
echo "Copying existing pages content..."
46+
cp -r "${EXISTING_DIR}"/* "${OUTPUT_DIR}/" 2>/dev/null || true
47+
rm -rf "${OUTPUT_DIR}/.git" # Remove git directory if present
6148
fi
6249
63-
# Create the preview directory
64-
PR_PREVIEW_DIR="$TEMP_DIR/pr-preview/pr-${PR_NUMBER}"
65-
rm -rf "$PR_PREVIEW_DIR"
66-
mkdir -p "$PR_PREVIEW_DIR"
50+
# Ensure .nojekyll exists (prevents Jekyll processing)
51+
touch "${OUTPUT_DIR}/.nojekyll"
6752
68-
# Copy built docs to preview directory
69-
cp -r "${GITHUB_WORKSPACE}/${DOCS_BUILD_DIR}"/* "$PR_PREVIEW_DIR/"
53+
# Prepare target directory
54+
FULL_TARGET="${OUTPUT_DIR}/${TARGET_PATH}"
55+
rm -rf "$FULL_TARGET"
56+
mkdir -p "$FULL_TARGET"
7057
71-
# Commit and push
72-
cd "$TEMP_DIR"
73-
git add .
74-
git commit -m "Deploy docs preview for PR #${PR_NUMBER} (commit ${COMMIT_SHA})" || echo "No changes to commit"
75-
git push origin gh-pages
58+
# Copy built docs to target directory
59+
cp -r "${DOCS_DIR}"/* "$FULL_TARGET/"
7660
77-
echo "Documentation preview deployed to gh-pages branch"
61+
echo "site_dir=${OUTPUT_DIR}" >> $GITHUB_OUTPUT

‎.github/actions/generate-docs-comment/action.yml‎

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,11 @@
1-
# This file defines a GitHub action used to generate the body content for a pull request (PR) comment,
1+
# This file defines a GitHub action used to generate the body content for a pull request comment,
22
# providing details and quick access links to the documentation preview generated for that PR.
3-
#
4-
# When integrated in a workflow, this action collects metadata (such as preview URL, changed documentation files,
5-
# build time, and commit SHA) and prepares a Markdown message that can be posted as a PR comment by subsequent workflow steps.
63
#
74
# Input Parameters:
8-
# - preview_url: (required) URL for the deployed documentation preview (GitHub Pages).
9-
# - changed_docs: (required) JSON array listing the documentation files changed in the PR.
10-
# - build_timestamp: (required) Timestamp (in UTC or specified format) when the docs preview was built.
11-
# - commit_sha: (required) Short SHA for the commit associated with the docs preview.
5+
# - preview_url: URL for the deployed documentation preview (GitHub Pages).
6+
# - changed_docs: JSON array listing the documentation files changed in the PR.
7+
# - build_timestamp: Timestamp (in UTC or specified format) when the docs preview was built.
8+
# - commit_sha: Short SHA for the commit associated with the docs preview.
129

1310
name: 'Generate Documentation Comment'
1411
description: 'Generates PR comment body for documentation preview'
@@ -32,11 +29,16 @@ runs:
3229
steps:
3330
- name: Generate comment body
3431
shell: bash
32+
env:
33+
PREVIEW_URL: ${{ inputs.preview_url }}
34+
CHANGED_DOCS: ${{ inputs.changed_docs }}
35+
BUILD_TIMESTAMP: ${{ inputs.build_timestamp }}
36+
COMMIT_SHA: ${{ inputs.commit_sha }}
3537
run: |
36-
preview_url="${{ inputs.preview_url }}"
37-
changed_docs='${{ inputs.changed_docs }}'
38-
build_timestamp="${{ inputs.build_timestamp }}"
39-
commit_sha="${{ inputs.commit_sha }}"
38+
preview_url="$PREVIEW_URL"
39+
changed_docs="$CHANGED_DOCS"
40+
build_timestamp="$BUILD_TIMESTAMP"
41+
commit_sha="$COMMIT_SHA"
4042
4143
cat << 'EOF' > comment.md
4244
## Documentation Preview

‎.github/actions/get-changed-docs/action.yml‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
#
33
# This action compares two commit SHAs (typically the base and head of a PR)
44
# and detects which `.rst` and `.md` files under the `docs/` directory were changed.
5-
# The list of changed documentation files is output as a JSON array, which can be used by subsequent workflow jobs—
6-
# for example, to generate targeted PR comments or drive conditional logic for documentation builds.
5+
# The list of changed documentation files is output as a JSON array, which can be used by subsequent workflow jobs
6+
# to generate targeted PR comments or drive conditional logic for documentation builds.
77
#
88
# Inputs:
99
# - base_sha: The base commit SHA for comparison (e.g., the PR target branch).
@@ -35,9 +35,12 @@ runs:
3535
- name: Detect changed documentation files
3636
id: detect-changes
3737
shell: bash
38+
env:
39+
BASE_SHA: ${{ inputs.base_sha }}
40+
HEAD_SHA: ${{ inputs.head_sha }}
3841
run: |
3942
# Get list of changed .rst and .md files in docs/
40-
changed_files=$(git diff --name-only ${{ inputs.base_sha }} ${{ inputs.head_sha }} -- 'docs/*.rst' 'docs/*.md' 'docs/**/*.rst' 'docs/**/*.md' | head -20)
43+
changed_files=$(git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- 'docs/*.rst' 'docs/*.md' 'docs/**/*.rst' 'docs/**/*.md' | head -20)
4144
echo "Changed documentation files:"
4245
echo "$changed_files"
4346

‎.github/actions/set-deploy-info/action.yml‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,11 @@
33
# - Outputs a current, UTC-formatted build timestamp.
44
# - Outputs the short (7-character) version of the commit SHA.
55
#
6-
# The typical use is as a step in a workflow that builds and deploys documentation previews for pull requests.
7-
# Downstream steps or jobs can use the resulting outputs to inform users, link to previews, and tag deployments.
8-
#
96
# Input parameters:
10-
# - repo_owner: (required) The GitHub username or organization name that owns the repository.
11-
# - repo_name: (required) The name of the repository.
12-
# - pr_number: (required) The pull request number that triggered the deployment.
13-
# - commit_sha: (required) The full SHA hash of the commit being built.
7+
# - repo_owner: The GitHub username or organization name that owns the repository.
8+
# - repo_name: The name of the repository.
9+
# - pr_number: The pull request number that triggered the deployment.
10+
# - commit_sha: The full SHA hash of the commit being built.
1411
#
1512
# Outputs:
1613
# - preview_url: The constructed GitHub Pages URL to this pull request's documentation preview.
@@ -51,17 +48,20 @@ runs:
5148
- name: Generate deployment info
5249
id: generate-info
5350
shell: bash
51+
env:
52+
REPO_OWNER: ${{ inputs.repo_owner }}
53+
REPO_NAME: ${{ inputs.repo_name }}
54+
PR_NUMBER: ${{ inputs.pr_number }}
55+
COMMIT_SHA_FULL: ${{ inputs.commit_sha }}
5456
run: |
55-
# Construct the GitHub Pages URL
56-
# Note: GitHub Pages serves gh-pages branch content at the root, not under /gh-pages/
57-
repo_owner="${{ inputs.repo_owner }}"
58-
repo_name="${{ inputs.repo_name }}"
59-
pr_number="${{ inputs.pr_number }}"
57+
repo_owner="$REPO_OWNER"
58+
repo_name="$REPO_NAME"
59+
pr_number="$PR_NUMBER"
6060
preview_url="https://${repo_owner}.github.io/${repo_name}/pr-preview/pr-${pr_number}"
6161
6262
# Get build timestamp in UTC
6363
build_timestamp=$(date -u '+%Y-%m-%d %H:%M:%S UTC')
64-
commit_sha="${{ inputs.commit_sha }}"
64+
commit_sha="$COMMIT_SHA_FULL"
6565
6666
echo "preview_url=$preview_url" >> $GITHUB_OUTPUT
6767
echo "build_timestamp=$build_timestamp" >> $GITHUB_OUTPUT

‎.github/workflows/build_documentation.yml‎

Lines changed: 0 additions & 125 deletions
This file was deleted.

0 commit comments

Comments
 (0)