Documentation #11341
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| on: | |
| workflow_dispatch: | |
| inputs: | |
| deployment_id: | |
| type: string | |
| description: The workflow id of the deployment that contains produced the documentation to publish. | |
| required: true | |
| version: | |
| required: true | |
| type: string | |
| description: 'The version that the documentation corresponds to, e.g. 0.3.1 or latest.' | |
| workflow_run: | |
| workflows: | |
| - Deployments | |
| - CI | |
| types: | |
| - completed | |
| name: Documentation | |
| concurrency: | |
| group: ${{ github.workflow }}${{ github.event.workflow_run.name }} # only one docs publishing can be run at a time, since all docs are published to the same location! | |
| cancel-in-progress: false | |
| jobs: | |
| publish_docs: | |
| name: Publish documentation | |
| runs-on: ubuntu-latest | |
| if: github.event_name == 'workflow_dispatch' || github.event.workflow_run.name == 'CI' || (github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.actor.id == '135836288') | |
| permissions: | |
| contents: write | |
| issues: write | |
| pull-requests: write | |
| actions: read | |
| environment: | |
| name: ${{ (github.event.workflow_run.name == 'CI' && 'default') || 'github-pages' }} | |
| url: ${{ vars.deployment_url || format('https://github.com/{0}', github.repository) }} | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| with: | |
| ref: ${{ (github.event.workflow_run.name == 'CI' && vars.preview_branch) || vars.live_branch }} | |
| token: ${{ (github.event.workflow_run.name == 'CI' && github.token) || secrets.REPO_BOT_ACCESS_TOKEN }} | |
| - name: Download artifacts | |
| id: artifacts | |
| run: | | |
| if ${{ github.event_name == 'workflow_dispatch' }}; then | |
| artifacts_url=https://api.github.com/repos/${{ github.repository }}/actions/runs/${{ inputs.deployment_id }}/artifacts | |
| else | |
| artifacts_url=${{ github.event.workflow_run.artifacts_url }} | |
| fi | |
| artifacts=$(gh api $artifacts_url -q '.artifacts[] | {name: .name, url: .archive_download_url}') | |
| artifact_name=cuda_quantum_docs | |
| docs_found=${{ github.event.workflow_run.name == 'CI' || false }} | |
| for artifact in `echo "$artifacts"`; do | |
| name=`echo $artifact | jq -r '.name'` | |
| if [ "$name" == "$artifact_name" ]; then | |
| url=`echo $artifact | jq -r '.url'` | |
| gh api $url > cuda_quantum_docs.zip | |
| docs_found=true && echo "docs_archive=cuda_quantum_docs.zip" >> $GITHUB_OUTPUT | |
| elif [ "$name" == "metadata_ci" ]; then | |
| url=`echo $artifact | jq -r '.url'` | |
| gh api $url > metadata.zip | |
| unzip -d metadata metadata.zip | |
| for file in `find metadata/ -type f`; do | |
| cat "$file" >> metadata.txt | |
| done | |
| rm -rf metadata metadata.zip | |
| fi | |
| done | |
| run_id=`echo $artifacts_url | rev | cut -d / -f 2 | rev` | |
| workflow_run=https://github.com/${{ github.repository }}/actions/runs/$run_id | |
| if $docs_found; then | |
| echo "Downloaded $artifact_name artifact from $workflow_run." >> $GITHUB_STEP_SUMMARY | |
| else | |
| echo "::error file=documentation.yml::Failed to find $artifact_name artifact from $workflow_run." | |
| exit 1; | |
| fi | |
| if [ -f metadata.txt ]; then | |
| pr_number=`cat metadata.txt | grep -o 'pr-number: \S*' | cut -d ' ' -f 2` | |
| pr_base=`cat metadata.txt | grep -o 'pr-base: \S*' | cut -d ' ' -f 2` | |
| rm metadata.txt && echo "pr_number=$pr_number" >> $GITHUB_OUTPUT | |
| fi | |
| if ${{ github.event_name == 'workflow_dispatch' }}; then | |
| echo "target_folder=${{ inputs.version }}" >> $GITHUB_OUTPUT | |
| else | |
| # Docs will be checked in under a different folder in the preview. | |
| head_branch=${pr_base:-${{ github.event.workflow_run.head_branch }}} | |
| if [ "$head_branch" == "main" ]; then | |
| echo "target_folder=latest" >> $GITHUB_OUTPUT | |
| elif ${{ github.event.workflow_run.name != 'CI' }} && [ "$head_branch" != "${head_branch#experimental/}" ]; then | |
| echo "Documentation for experimental features will not be published." | |
| echo "Instead, please edit the README in docker/release/ to describe the feature and link any additional resources." | |
| elif ${{ github.event.workflow_run.name != 'CI' }} && [ "$head_branch" != "${head_branch#features/}" ]; then | |
| echo "Documentation for feature branches will not be published." | |
| elif ${{ github.event.workflow_run.name != 'CI' }} && [ "$head_branch" != "${head_branch#staging/}" ]; then | |
| # Only publish docs if no release branch exists for that version. | |
| version=`echo ${head_branch#staging/} | (egrep -o "^v?([0-9]{1,}\.)+[0-9]{1,}$" || true)` | |
| gh api repos/${{ github.repository }}/branches \ | |
| -H "Accept: application/vnd.github+json" \ | |
| -H "X-GitHub-Api-Version: 2022-11-28" \ | |
| --paginate --jq '.[].name | select(startswith("releases/"))' \ | |
| > release_branches.txt | |
| if [ -n "$(cat release_branches.txt | (egrep -o "^releases/v?${version}$" || true))" ]; then | |
| echo "A release branch exists for version $version. Documentation from staging branch will not be published." >> $GITHUB_STEP_SUMMARY | |
| else | |
| echo "target_folder=${version#v}" >> $GITHUB_OUTPUT | |
| if [ -z "${version:-$pr_number}" ]; then | |
| echo "Unrecognized docs version. Documentation will not be published." >> $GITHUB_STEP_SUMMARY | |
| fi | |
| fi | |
| else | |
| version=`echo ${head_branch#releases/} | (egrep -o "^v?([0-9]{1,}\.)+[0-9]{1,}$" || true)` | |
| echo "target_folder=${version#v}" >> $GITHUB_OUTPUT | |
| if [ -z "${version:-$pr_number}" ]; then | |
| echo "Unrecognized docs version. Documentation will not be published." >> $GITHUB_STEP_SUMMARY | |
| fi | |
| fi | |
| fi | |
| env: | |
| GH_TOKEN: ${{ github.token }} | |
| - name: Push docs update | |
| id: push_docs | |
| if: steps.artifacts.outputs.docs_archive != '' && (steps.artifacts.outputs.target_folder != '' || steps.artifacts.outputs.pr_number != '') | |
| run: | | |
| pr_number=${{ steps.artifacts.outputs.pr_number }} | |
| target_folder=${pr_number:+pr-$pr_number} | |
| target_folder="${target_folder:-${{ steps.artifacts.outputs.target_folder }}}" | |
| rm -rf "$target_folder" | |
| unzip -d "$target_folder" "${{ steps.artifacts.outputs.docs_archive }}" | |
| git config --global user.name "cuda-quantum-bot" | |
| git config --global user.email "cuda-quantum-bot@users.noreply.github.com" | |
| if [ -f create_redirects.sh ]; then | |
| bash create_redirects.sh >> $GITHUB_STEP_SUMMARY | |
| fi | |
| git add "$target_folder" | |
| docs_changed=`git diff --cached --exit-code > /dev/null && echo false || echo true` | |
| if ${{ github.event_name == 'workflow_dispatch' }}; then | |
| git commit -m "Docs update triggered manually for version ${{ inputs.version }} (workflow: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})." | |
| elif [ -n "$pr_number" ]; then | |
| git commit --allow-empty -m "Docs preview for PR #$pr_number." | |
| else | |
| git commit --allow-empty -m "Docs update triggered by deployment on head branch ${{ github.event.workflow_run.head_branch }}, commit ${{ github.event.workflow_run.head_sha }}." | |
| fi | |
| git config pull.rebase true | |
| git pull --no-edit && git push | |
| # For the docs preview, we determine whether docs changed compared to the eventual target folder. | |
| if [ "$target_folder" != "${{ steps.artifacts.outputs.target_folder }}" ]; then | |
| rm -rf "${{ steps.artifacts.outputs.target_folder }}" | |
| mv "$target_folder" "${{ steps.artifacts.outputs.target_folder }}" | |
| git add "${{ steps.artifacts.outputs.target_folder }}" | |
| docs_changed=`git diff --cached --exit-code > /dev/null && echo false || echo true` | |
| fi | |
| pr_comment='**CUDA Quantum Docs Bot:** ' | |
| if $docs_changed; then | |
| branch_name=`git rev-parse --abbrev-ref HEAD` | |
| preview_link=https://htmlpreview.github.io/?https://github.com/${{ github.repository }}/blob/${branch_name}/${target_folder}/index.html | |
| pr_comment+="A preview of the documentation can be found [here]($preview_link)." | |
| echo "$pr_comment" >> $GITHUB_STEP_SUMMARY | |
| else | |
| pr_comment+='This PR contains no documentation changes.' | |
| echo "No documentation changes." >> $GITHUB_STEP_SUMMARY | |
| fi | |
| echo "pr_comment=$pr_comment" >> $GITHUB_OUTPUT | |
| - name: Comment on PR | |
| if: steps.artifacts.outputs.pr_number != '' && steps.push_docs.outcome != 'skipped' | |
| continue-on-error: true # PR may be locked by the time this workflow runs if auto-merge is set to true | |
| uses: peter-evans/create-or-update-comment@v3 | |
| with: | |
| issue-number: ${{ steps.artifacts.outputs.pr_number }} | |
| body: ${{ steps.push_docs.outputs.pr_comment }} | |
| edit-mode: replace |