Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Build docs in GitHub for review #954

Closed
wants to merge 3 commits into from
Closed

Build docs in GitHub for review #954

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
175d2b6
Build docs in GitHub for review
mikemckiernan Jan 27, 2025
dfd7f97
Add docs publishing
mikemckiernan Jan 27, 2025
2781c2d
Describe how to publish docs
mikemckiernan Jan 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 54 additions & 0 deletions .github/workflows/docs-build-pr.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
name: docs-build-pr

on:
pull_request:
branches: [develop]
types: [opened, synchronize]

env:
GH_TOKEN: ${{ github.token }}

concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true

jobs:
build-docs:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Build image
uses: docker/build-push-action@v6
with:
context: docs
file: docs/Dockerfile
load: true
tags: pr-image:${{ github.sha }}
- name: Build docs
run: |
docker run -v $(pwd):/work -w /work pr-image:${{ github.sha }} sphinx-build -b html docs _build/docs
- name: Delete unnecessary files
run: |
sudo find _build -name .doctrees -prune -exec rm -rf {} \;
sudo find _build -name .buildinfo -exec rm {} \;
- name: Upload HTML
uses: actions/upload-artifact@v4
with:
name: html-build-artifact
path: _build/docs
if-no-files-found: error
retention-days: 1
- name: Store PR information
run: |
mkdir ./pr
echo ${{ github.event.number }} > ./pr/pr.txt
echo ${{ github.event.pull_request.merged }} > ./pr/merged.txt
echo ${{ github.event.action }} > ./pr/action.txt
- name: Upload PR information
uses: actions/upload-artifact@v4
with:
name: pr
path: pr/
198 changes: 198 additions & 0 deletions .github/workflows/docs-build.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,198 @@
name: docs-build

on:
push:
branches: [develop]
tags:
- docs-v*
- v*
workflow_dispatch:

env:
REGISTRY: ghcr.io
IMAGE_NAME: ${{ github.repository }}-docs
TAG: 0.1.0
GH_TOKEN: ${{ github.token }}

concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true

jobs:
dockerfile-changed:
runs-on: ubuntu-latest
permissions:
contents: read
packages: read
outputs:
changed: ${{ steps.change.outputs.changed }}
image: ${{ steps.change.outputs.image }}
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Log in to Container Registry
uses: docker/login-action@v3
with:
registry: ${{ env.REGISTRY }}
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Detect change
id: change
shell: bash
run: |
export COMMIT_SHORT_SHA="${GITHUB_SHA:0:8}"
if ! docker manifest inspect "${REGISTRY}/${IMAGE_NAME,,}:${TAG}" 2>&1 > /dev/null ; then
echo "image not found...${REGISTRY}/${IMAGE_NAME,,}:${TAG}"
export NEEDS_IMAGE=true
fi
def_branch=$(gh api "repos/${GITHUB_REPOSITORY}" -q '.default_branch')
git fetch origin "${def_branch}"
files=$(git diff --name-only "${GITHUB_SHA}" FETCH_HEAD | tr '\n' ' ')
echo "${files}"
if echo "${files}" | grep -q "docs/poetry.lock/\|docs/Dockerfile"; then export NEEDS_IMAGE=true ; fi
if [[ "${NEEDS_IMAGE}" ]]; then
echo "changed=true" >> "$GITHUB_OUTPUT"
if [[ "${{ github.event_name }}" == 'pull_request' ]]; then
echo "image=${REGISTRY}/${IMAGE_NAME,,}:${COMMIT_SHORT_SHA}" >> "$GITHUB_OUTPUT"
else
echo "image=${REGISTRY}/${IMAGE_NAME,,}:${TAG}" >> "$GITHUB_OUTPUT"
fi
else
echo "changed=false" >> "$GITHUB_OUTPUT"
echo "image=${REGISTRY}/${IMAGE_NAME,,}:${TAG}" >> "$GITHUB_OUTPUT"
fi

build-and-push-image:
needs: dockerfile-changed
if: needs.dockerfile-changed.outputs.changed == 'true'
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to Container Registry
uses: docker/login-action@v3
with:
registry: ${{ env.REGISTRY }}
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Build and push
uses: docker/build-push-action@v6
with:
context: docs
file: docker/Dockerfile
push: true
tags: ${{ needs.dockerfile-changed.outputs.image }}

build-docs:
needs: [dockerfile-changed, build-and-push-image]
container:
image: ${{ needs.dockerfile-changed.outputs.image }}
if: ${{ always() }}
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Build docs
run: |
sphinx-build -b html docs _build/docs
- name: Delete unnecessary files
run: |
find _build -name .doctrees -prune -exec rm -rf {} \;
find _build -name .buildinfo -exec rm {} \;
- name: Upload HTML
uses: actions/upload-artifact@v4
with:
name: html-build-artifact
path: _build/docs
if-no-files-found: error
retention-days: 1
- name: Store PR information
if: github.event_name == 'pull_request'
run: |
mkdir ./pr
echo ${{ github.event.number }} > ./pr/pr.txt
echo ${{ github.event.pull_request.merged }} > ./pr/merged.txt
echo ${{ github.event.action }} > ./pr/action.txt
- name: Upload PR information
if: ${{ github.event_name == 'pull_request' }}
uses: actions/upload-artifact@v4
with:
name: pr
path: pr/

store-html:
needs: [build-docs]
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
ref: "gh-pages"
- name: Initialize Git configuration
run: |
git config user.name docs-build
git config user.email [email protected]
- name: Download artifacts
uses: actions/download-artifact@v4
with:
name: html-build-artifact
- name: Copy HTML directories
run: |
ls -asl
for i in `ls -d *`
do
echo "Git adding ${i}"
git add "${i}"
done
- name: Check or create dot-no-jekyll file
run: |
if [ -f ".nojekyll" ]; then
echo "The dot-no-jekyll file already exists."
exit 0
fi
touch .nojekyll
git add .nojekyll
- name: Check or create redirect page
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
resp=$(grep 'http-equiv="refresh"' index.html 2>/dev/null) || true
if [ -n "${resp}" ]; then
echo "The redirect file already exists."
exit 0
fi
# If any of these commands fail, fail the build.
def_branch=$(gh api "repos/${GITHUB_REPOSITORY}" --jq ".default_branch")
html_url=$(gh api "repos/${GITHUB_REPOSITORY}/pages" --jq ".html_url")
# Beware ugly quotation mark avoidance in the foll lines.
echo '<!DOCTYPE html>' > index.html
echo '<html>' >> index.html
echo ' <head>' >> index.html
echo ' <title>Redirect to documentation</title>' >> index.html
echo ' <meta charset="utf-8">' >> index.html
echo ' <meta http=equiv="refresh" content="3; URL='${html_url}${def_branch}'/index.html">' >> index.html
echo ' <link rel="canonical" href="'${html_url}${def_branch}'/index.html">' >> index.html
echo ' <script language="javascript">' >> index.html
echo ' function redirect() {' >> index.html
echo ' window.location.assign("'${html_url}${def_branch}'/index.html")' >> index.html
echo ' }' >> index.html
echo ' </script>' >> index.html
echo ' </head>' >> index.html
echo ' <body onload="redirect()">' >> index.html
echo ' <p>Please follow the link to the <a href="'${html_url}${def_branch}'/index.html">' >> index.html
echo ${def_branch}'</a> branch documentation.</p>' >> index.html
echo ' </body>' >> index.html
echo '</html>' >> index.html
git add index.html
- name: Commit changes to the GitHub Pages branch
run: |
git status
if git commit -m 'Pushing changes to GitHub Pages.'; then
git push -f
else
echo "Nothing changed."
fi
18 changes: 18 additions & 0 deletions .github/workflows/docs-preview-pr.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
name: docs-preview-pr

on:
workflow_run:
workflows: [ docs-build-pr ]
types: [ completed ]
branches-ignore: [ main ]

concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true

env:
WF_ID: ${{ github.event.workflow_run.id }}

jobs:
preview:
uses: nvidia-merlin/.github/.github/workflows/docs-preview-pr-common.yaml@main
11 changes: 11 additions & 0 deletions .github/workflows/docs-remove-stale-reviews.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
name: docs-remove-stale-reviews

on:
schedule:
# 42 minutes after 0:00 UTC on Sundays
- cron: "42 0 * * 0"
workflow_dispatch:

jobs:
remove:
uses: nvidia-merlin/.github/.github/workflows/docs-remove-stale-reviews-common.yaml@main
Loading
Loading