Updating build process and gh-pages fork publications #3

Workflow file for this run

.github/workflows/build_and_deploy_docs.yml at df05d05

	#
	# GitHub Actions Workflow for building and publishing the CF conventions and
	# conformance docs.
	#
	# For more information on the actions used in this workflow, please see:
	# https://github.com/actions/checkout
	# https://github.com/Analog-inc/asciidoctor-action
	# https://github.com/actions/upload-artifact
	# https://github.com/actions/download-artifact

	name: Asciidoctor Build Workflow
	on:
	workflow_dispatch: # Manual trigger
	pull_request: # On pull request to main
	branches: [main]
	push: # On push any branch (excluding gh-pages)
	branches-ignore: [gh-pages]
	release: # On release published
	types:
	- published

	# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
	permissions:
	contents: write
	pages: write
	id-token: write

	# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
	# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
	concurrency:
	group: "pages"
	cancel-in-progress: false

	env:
	DESIRED_BRANCH: "gh-pages" # Branch to use for GitHub Pages
	DESIRED_PATH: "/" # Path to use for GitHub Pages
	DESIRED_BUILD_TYPE: "legacy" # Build type for GitHub Pages
	GH_TOKEN: ${{ github.token }}

	jobs:
	# Job to build documents
	build_docs:
	name: Build Documentation
	runs-on: ubuntu-latest
	if: ${{ !(github.event_name == 'pull_request' && github.event.action == 'closed') }}

	steps:
	- name: Checkout Repository
	uses: actions/checkout@v4

	- name: Set Release Tag and Date
	if: github.event_name == 'release'
	run: \|
	echo "CF_FINAL=True" >> $GITHUB_ENV

	- name: Build Documentation
	uses: Analog-inc/asciidoctor-action@v1
	with:
	shellcommand: 'make all'

	- name: Prepare and Update Index Page
	run: \|
	sudo cp -p .github/gh-pages/index.html build/
	PATH_REVISION="${GITHUB_REPOSITORY}/${GITHUB_REF_TYPE}/${GITHUB_REF_NAME}@${GITHUB_SHA:0:7}"
	sudo sed -i "s/Latest/${PATH_REVISION//\//\\/}/" build/index.html

	- name: Upload Artifacts
	uses: actions/upload-artifact@v4
	with:
	name: documentation_artifacts
	path: build/


	# Job to publish documentation to GitHub Pages
	publish_docs:
	name: Publish Documentation
	runs-on: ubuntu-latest
	needs: build_docs
	steps:
	- name: Verify Pre-installed Tools
	run: \|
	jq --version
	tree --version
	gh --version

	- name: Checkout Repository
	uses: actions/checkout@v4

	- name: Check and Create GH Pages Branch
	run: \|
	if ! git ls-remote --exit-code origin gh-pages > /dev/null; then
	echo "Creating the $DESIRED_BRANCH branch..."
	git checkout --orphan $DESIRED_BRANCH
	git rm -rf . \|\| true
	echo "# GitHub Pages" > index.html
	git add index.html
	git commit -m "Initialize $DESIRED_BRANCH branch"
	git push origin $DESIRED_BRANCH
	else
	echo "The $DESIRED_BRANCH branch already exists."
	fi

	- name: Enforce GitHub Pages Configuration
	run: \|
	# Fetch current GitHub Pages configuration
	API_RESPONSE=$(gh api repos/${{ github.repository }}/pages \|\| echo "{}")

	# Extract current configuration
	IS_ENABLED=$(echo "$API_RESPONSE" \| jq -r '.source // empty')
	BUILD_TYPE=$(echo "$API_RESPONSE" \| jq -r '.build_type // empty')
	SOURCE_BRANCH=$(echo "$API_RESPONSE" \| jq -r '.source.branch // empty')
	SOURCE_PATH=$(echo "$API_RESPONSE" \| jq -r '.source.path // empty')

	# Enforce configuration if any setting is incorrect or GitHub Pages is not enabled
	if [[ -z "$IS_ENABLED" ]] \|\| [[ "$BUILD_TYPE" != "$DESIRED_BUILD_TYPE" ]] \|\| [[ "$SOURCE_BRANCH" != "$DESIRED_BRANCH" ]] \|\| [[ "$SOURCE_PATH" != "$DESIRED_PATH" ]]; then
	echo "Enforcing GitHub Pages configuration..."
	gh api repos/${{ github.repository }}/pages \
	--method POST \
	--input - <<< "{\"source\":{\"branch\":\"$DESIRED_BRANCH\",\"path\":\"$DESIRED_PATH\"}, \"build_type\":\"$DESIRED_BUILD_TYPE\"}"
	echo "GitHub Pages has been configured: Branch='${DESIRED_BRANCH}', Path='${DESIRED_PATH}', Build Type='${DESIRED_BUILD_TYPE}'."
	else
	echo "GitHub Pages is already configured correctly: Branch='${DESIRED_BRANCH}', Path='${DESIRED_PATH}', Build Type='${DESIRED_BUILD_TYPE}'."
	fi

	- name: Checkout gh-pages Branch into Subdirectory
	uses: actions/checkout@v4
	with:
	repository: ${{ github.repository }}
	ref: ${{ env.DESIRED_BRANCH }}
	path: gh-pages

	- name: Determine Target Directory and Add .nojekyll
	run: \|
	cd gh-pages
	# Ensure .nojekyll exists
	[ ! -f .nojekyll ] && touch .nojekyll
	# Determine target directory based on the event type
	if [[ ${{ github.event_name }} == 'release' ]]; then
	echo "TARGET_DIR=release/${GITHUB_REF_NAME}" >> $GITHUB_ENV
	elif [[ ${{ github.event_name }} == 'pull_request' ]]; then
	BASE_REPO_FULL_NAME=${{ github.event.pull_request.base.repo.full_name }}
	PR_NUMBER=${{ github.event.pull_request.number }}
	echo "TARGET_DIR=pr-preview/${BASE_REPO_FULL_NAME}/${PR_NUMBER}" >> $GITHUB_ENV
	else
	echo "TARGET_DIR=${GITHUB_REF_TYPE}/${GITHUB_REF_NAME}" >> $GITHUB_ENV
	fi

	- name: Download Artifacts
	uses: actions/download-artifact@v4
	with:
	name: documentation_artifacts
	path: gh-pages/build/

	- name: Verify Build Artifacts
	run: \|
	cd gh-pages
	if [ ! "$(ls -A build)" ]; then
	echo "Build artifacts are missing!" >&2
	exit 1
	fi

	- name: Publish Documentation
	if: ${{ !(github.event_name == 'pull_request' && github.event.action == 'closed') }}
	run: \|
	cd gh-pages
	mkdir -p ${{ env.TARGET_DIR }}
	cp -p build/* ${{ env.TARGET_DIR }}/
	rm -rf build/
	tree -T "${GITHUB_REPOSITORY}" --dirsfirst --prune --noreport \
	-I "index.html\|README.md" -H . -o index.html

	- name: Cleanup PR Artifacts
	if: ${{ github.event_name == 'pull_request' && github.event.action == 'closed' }}
	run: \|
	cd gh-pages
	rm -rf ${{ env.TARGET_DIR }}

	- name: Build Index Tree
	run: \|
	cd gh-pages
	tree -T "${GITHUB_REPOSITORY}" --dirsfirst --prune --noreport \
	-I "index.html\|README.md" -H . -o index.html

	- name: Commit and Push Changes
	run: \|
	cd gh-pages
	git add --all
	git config user.name "github-actions[bot]"
	git config user.email "github-actions[bot]@users.noreply.github.com"
	git commit -m "Update documentation from ${GITHUB_REPOSITORY}@${GITHUB_SHA}" \|\| echo "No changes to commit; skipping push."
	git push

	- name: Post PR Comment with Preview Link
	if: ${{ github.event_name == 'pull_request' && github.event.action != 'closed' }}
	uses: marocchino/sticky-pull-request-comment@v2
	with:
	header: ":page_facing_up: CF Preview"
	hide_and_recreate: true
	hide_classify: "OUTDATED"
	message: \|
	The documentation build was successful! 🎉

	You can view the updated documentation here:
	[View Documentation Preview](https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/${{ env.TARGET_DIR }}/index.html)

	- name: Upload Documentation files as Release Asset
	if: github.event_name == 'release'
	run: \|
	export TARGET_DIR=${{ env.TARGET_DIR }}
	gh release upload ${{ github.event.release.tag_name }} \
	gh-pages/${TARGET_DIR}/cf-conventions.html \
	gh-pages/${TARGET_DIR}/cf-conventions.pdf \
	gh-pages/${TARGET_DIR}/conformance.html \
	gh-pages/${TARGET_DIR}/conformance.pdf \
	--clobber

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updating build process and gh-pages fork publications #3

Workflow file

Updating build process and gh-pages fork publications #3

Jobs

Run details

Workflow file for this run