Automated Documentation Build #614
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
| # This workflow builds versioned copies of Prefect's documentation. | |
| # It is triggered automatically by two events in PrefectHQ/prefect: | |
| # | |
| # 1. A new release is published | |
| # 2. A new commit is pushed to main branch's docs directory | |
| # | |
| # It also can be triggered manually by a user with write access to | |
| # the PrefectHQ/docs repository. In this case, the user must provide | |
| # a version number as an input to the workflow. | |
| name: Documentation Build | |
| permissions: {} | |
| # Limit concurrency by workflow/branch combination. | |
| # | |
| # For pull request builds, pushing additional changes to the | |
| # branch will cancel prior in-progress and pending builds. | |
| # | |
| # For builds triggered on a branch push, additional changes | |
| # will wait for prior builds to complete before starting. | |
| # | |
| # https://docs.github.com/en/actions/using-jobs/using-concurrency | |
| concurrency: | |
| group: ${{ github.workflow }}-${{ github.ref }} | |
| cancel-in-progress: ${{ github.event_name == 'pull_request' }} | |
| on: | |
| repository_dispatch: | |
| types: | |
| - "Automated Documentation Build" | |
| workflow_dispatch: | |
| inputs: | |
| version: | |
| description: 'The release tag or branch to build and deploy | |
| (e.g., "2.8.0", "2.8.0-docs-hotfix"). | |
| Use `unreleased` to build directly from the main branch of `PrefectHQ/prefect`.' | |
| type: string | |
| required: true | |
| default: 'unreleased' | |
| display_name: | |
| description: 'The display name for the version (e.g., 2.8.0, 2.8.x, 2.7.x). | |
| Leave blank to use the version number.' | |
| type: string | |
| required: false | |
| default: '' | |
| jobs: | |
| build_docs_version: | |
| runs-on: ubuntu-latest | |
| permissions: | |
| contents: write | |
| pull-requests: write | |
| steps: | |
| - name: Checkout docs | |
| uses: actions/checkout@v3 | |
| with: | |
| ref: main | |
| fetch-depth: 0 | |
| path: ./docs | |
| - name: Set docs version | |
| run: | | |
| version="${{ github.event.client_payload.version }}" | |
| if [[ -z "$version" ]]; then | |
| version="${{ github.event.inputs.version }}" | |
| fi | |
| # if version is missing, exit with error | |
| if [[ -z "$version" ]]; then | |
| echo "Can't build versioned docs without a version!" | |
| exit 1 | |
| fi | |
| # If the display name is blank, use the version number as | |
| # the display name | |
| display_name="${{ github.event.client_payload.display_name }}" | |
| if [[ -z "$display_name" ]]; then | |
| display_name="${{ github.event.inputs.display_name }}" | |
| fi | |
| if [[ -z "$display_name" ]]; then | |
| display_name="$version" | |
| fi | |
| echo "version=$version" >> $GITHUB_ENV | |
| echo "display_name=$display_name" >> $GITHUB_ENV | |
| - name: Setup Python | |
| uses: actions/setup-python@v4 | |
| with: | |
| python-version: 3.10.x | |
| - name: Clone PrefectHQ/prefect | |
| run: | | |
| version="${{ env.version }}" | |
| if [[ $version == "unreleased" ]]; then | |
| git clone --depth 1 https://github.com/PrefectHQ/prefect.git prefect_source | |
| else | |
| git clone --branch "$version" --depth 1 https://github.com/PrefectHQ/prefect.git prefect_source | |
| fi | |
| working-directory: ${{ github.workspace }}/ | |
| - name: Install Prefect and dependencies | |
| run: | | |
| pip install --upgrade pip | |
| pip install --upgrade --upgrade-strategy eager -e ".[dev]" | |
| working-directory: ${{ github.workspace }}/prefect_source | |
| - name: Install PrefectHQ/mkdocs-material-insiders | |
| env: | |
| MKDOCS_MATERIAL_INSIDERS_CONTENTS_RO: ${{ secrets.MKDOCS_MATERIAL_INSIDERS_CONTENTS_RO }} | |
| run: | | |
| pip install git+https://oauth2:[email protected]/PrefectHQ/mkdocs-material-insiders.git@706cb730a2efbc1032226af3937207223cb07e05 | |
| sudo apt-get install -y libcairo2 | |
| - name: Install Python dependencies | |
| run: | | |
| pip install -r requirements.txt | |
| working-directory: ${{ github.workspace }}/docs | |
| - name: Set branch name | |
| run: | | |
| version="${{ env.version }}" | |
| display_name="${{ env.display_name }}" | |
| timestamp="$(date +%s)" | |
| # create branch_display_name from display_name by replacing all | |
| # characters disallowed in git branch names with hyphens | |
| branch_display_name="$(echo "$display_name" | tr -c '[:alnum:]._' '-' | tr -s '-')" | |
| echo "branch_name=update-docs-$branch_display_name-$timestamp" >> $GITHUB_ENV | |
| echo "timestamp=$timestamp" >> $GITHUB_ENV | |
| - name: Update docs | |
| env: | |
| AMPLITUDE_API_KEY: ${{ vars.AMPLITUDE_API_KEY }} | |
| AMPLITUDE_URL: ${{ vars.AMPLITUDE_URL }} | |
| run: | | |
| git config user.name "GitHub Actions Bot" | |
| git config user.email "[email protected]" | |
| version="${{ env.version }}" | |
| display_name="${{ env.display_name }}" | |
| branch_name="${{ env.branch_name }}" | |
| # remove the 'latest' alias so we can re-add it later | |
| python ./utilities/remove-docs-alias.py --versions-file-path ./versions/versions.json | |
| git add ./versions/versions.json | |
| git commit -m "Update versions.json" | |
| # create the version branch, otherwise mike will create a branch | |
| # that has no common history with main | |
| git checkout -b $branch_name | |
| git checkout main | |
| ln -s ../prefect_source/mkdocs.yml | |
| ln -s ../prefect_source/mkdocs.insiders.yml | |
| ln -s ../prefect_source/src ./src | |
| ln -s ../prefect_source/docs ./docs | |
| # append the contents of ./overrides/templates/outdated.html to | |
| # ./docs/overrides/main.html | |
| cat ./overrides/templates/outdated.html >> ./docs/overrides/main.html | |
| # if the version is anything other than 'unreleased', append the contents | |
| # of ./overrides/stylesheets/not-latest.css to ./docs/stylesheets/extra.css | |
| if [[ $version != "latest" ]]; then | |
| cat ./overrides/stylesheets/not-latest.css >> ./docs/stylesheets/extra.css | |
| fi | |
| # if there's a file named <version>.css in ./overrides/stylesheets, | |
| # append it to ./docs/stylesheets/extra.css | |
| if [[ -f ./overrides/stylesheets/$version.css ]]; then | |
| cat ./overrides/stylesheets/$version.css >> ./docs/stylesheets/extra.css | |
| fi | |
| # add version string we can reference in Mkdocs templates | |
| sed -i "/extra:/a\ version_string: $display_name" ./mkdocs.yml | |
| # generate API docs | |
| prefect dev build-docs | |
| # If the release we're building docs for is the newest release, | |
| # also build the 'latest' docs version. This ensures that the | |
| # docs site defaults to showing users docs for the most recently released | |
| # Prefect version. | |
| newest_release=$(python utilities/get-newest-version.py --versions-file-path ./versions/versions.json --build-version "$version") | |
| echo "Newest release is $newest_release. Version being built is $version." | |
| if [[ "$newest_release" == "$version" ]]; then | |
| echo "Updating 'latest' docs version with $version." | |
| mike deploy --config-file ./mkdocs.insiders.yml --update-aliases --branch $branch_name --deploy-prefix=versions "$display_name" latest | |
| # There is a bug in Mike where image url aliases don't get rewritten to latest. | |
| # As of Sept 2023 Mike version 1.2. | |
| # Known issue that should be fixed in Mike 2.0. | |
| # https://github.com/jimporter/mike/issues/157 | |
| # For now, copying the latest numbered version folder to "latest" | |
| # so someone doesn't have to do it manually. | |
| # This attempted fix doesn't work b/c the folder isn't there yet- PR needs accepted first. | |
| # cp ./versions/"$version" ./versions/latest | |
| else | |
| echo "Updating previous docs version with $version." | |
| mike deploy --config-file ./mkdocs.insiders.yml --update-aliases --branch $branch_name --deploy-prefix=versions "$display_name" | |
| fi | |
| # Save newest version check to GITHUB_ENV so we can use it later | |
| is_newest_release=false | |
| if [[ "$newest_release" == "$version" ]]; then | |
| is_newest_release=true | |
| fi | |
| echo "is_newest_release=$is_newest_release" >> $GITHUB_ENV | |
| # clean up | |
| rm -rf site | |
| unlink ./src | |
| unlink ./docs | |
| unlink ./mkdocs.yml | |
| unlink ./mkdocs.insiders.yml | |
| working-directory: ${{ github.workspace }}/docs | |
| - name: Update Netlify TOML | |
| env: | |
| PREFECT_SOURCE: ${{ github.workspace }}/prefect_source | |
| run: | | |
| version="${{ env.version }}" | |
| # If version is not 'unreleased', skip this step. We should only need to update | |
| # the Netlify TOML when building docs for commits to Prefect's main branch. | |
| if [[ $version != "unreleased" ]]; then | |
| exit 0 | |
| fi | |
| git checkout $branch_name | |
| echo "Merging Netlify TOML overrides and additions..." | |
| python build-netlify-config.py \ | |
| --input-config-path "$PREFECT_SOURCE/netlify.toml" \ | |
| --overrides-path ./netlify.overrides.toml \ | |
| --additions-path ./netlify.additions.toml \ | |
| --output-config-path ./netlify_temp.toml | |
| # If $GITHUB_WORKSPACE/docs/netlify.toml is missing, | |
| # or exist but differs from ./netlify_temp.toml, | |
| # move ./netlify_temp.toml to $GITHUB_WORKSPACE/docs/netlify.toml. | |
| # otherwise, just remove ./netlify_temp.toml | |
| echo "Checking if Netlify TOML needs to be updated..." | |
| if [[ ! -f $GITHUB_WORKSPACE/docs/netlify.toml ]] || \ | |
| [[ $(diff $GITHUB_WORKSPACE/docs/netlify.toml ./netlify_temp.toml) ]]; then | |
| echo "Updating Netlify TOML..." | |
| mv ./netlify_temp.toml $GITHUB_WORKSPACE/docs/netlify.toml | |
| # commit the change | |
| git add $GITHUB_WORKSPACE/docs/netlify.toml | |
| git commit -m "Update Netlify TOML for version $version" | |
| else | |
| rm ./netlify_temp.toml | |
| fi | |
| working-directory: ${{ github.workspace }}/docs/overrides/netlify | |
| - name: Update Netlify edge functions | |
| env: | |
| PREFECT_SOURCE: ${{ github.workspace }}/prefect_source | |
| run: | | |
| echo "Updating Netlify Edge Functions..." | |
| rm -f ./netlify/edge-functions/* | |
| cp $PREFECT_SOURCE/netlify/edge-functions/* ./netlify/edge-functions/ | |
| git add ./netlify/edge-functions | |
| if ! git diff --quiet --cached; then | |
| git commit -m "Update Netlify edge functions" | |
| fi | |
| working-directory: ${{ github.workspace }}/docs | |
| - name: Sort docs versions | |
| run: | | |
| git checkout $branch_name | |
| python ./utilities/sort-docs-versions.py --versions-file-path ./versions/versions.json | |
| git add ./versions/versions.json | |
| git commit -m "Sort docs versions" | |
| working-directory: ${{ github.workspace }}/docs | |
| - name: Create Pull Request | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| run: | | |
| version="${{ env.version }}" | |
| display_name="${{ env.display_name }}" | |
| branch_name="${{ env.branch_name }}" | |
| is_newest_release="${{ env.is_newest_release }}" | |
| # set the PR title | |
| if [[ $display_name == "unreleased" ]]; then | |
| pull_request_title="Update unreleased documentation" | |
| else | |
| pull_request_title="Update documentation for $display_name" | |
| fi | |
| # Delete any existing pull requests that are open for this version | |
| # by checking against pull_reqeust_title because the new PR will | |
| # supersede the old one. | |
| gh pr list --state open --json title --jq '.[] | select(.title == "$pull_request_title") | .number' | \ | |
| xargs -I {} gh pr close {} | |
| # push the branch to GitHub | |
| git push origin $branch_name | |
| # create the PR | |
| gh pr create --base main --head $branch_name \ | |
| --title "$pull_request_title" \ | |
| --body "Automated documentation update for $display_name" \ | |
| --label "documentation" \ | |
| # auto-merge the PR if the build was triggered by a commit to Prefect's main | |
| # repo. This is because we only want to auto-merge PRs automatically | |
| # triggered docs builds. Manual builds should be reviewed by a human. | |
| if [[ $GITHUB_EVENT_NAME == "repository_dispatch" ]]; then | |
| # give the PR a few seconds to be created before trying to auto-merge it | |
| sleep 10 | |
| gh pr merge --squash $branch_name | |
| fi | |
| working-directory: ${{ github.workspace }}/docs |