Integrate Design Documents into docs site #5783
This file contains hidden or 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
| name: Make Documentation | |
| on: | |
| push: | |
| branches: [ master, development ] | |
| pull_request: | |
| branches: [ master, development ] | |
| types: [ opened, synchronize, reopened, closed ] | |
| permissions: | |
| contents: write | |
| pull-requests: write | |
| env: | |
| REPO_METADATA_SHAS: repo-metadata-shas.txt | |
| jobs: | |
| build: | |
| if: github.event.action != 'closed' | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - name: apt install | |
| uses: nick-invision/retry@v2.4.0 | |
| with: | |
| max_attempts: 5 | |
| timeout_minutes: 15 | |
| command: | | |
| sudo apt-get update | |
| sudo apt-get install -yqq build-essential libxml2-dev zlib1g-dev bison flex libcairo2-dev pkg-config | |
| - name: Set up Python install env | |
| run: | | |
| python3 -m venv venv | |
| . venv/bin/activate | |
| python -m pip install -U pip | |
| echo "export MAKEFLAGS=\"PYTHON=$(which python) PIP_OPTS=-U\"" >> ~/.bashrc | |
| - name: Install Python dependencies | |
| uses: nick-invision/retry@v2.4.0 | |
| with: | |
| max_attempts: 5 | |
| timeout_minutes: 15 | |
| command: | | |
| . venv/bin/activate | |
| pip install pygithub | |
| make install | |
| - name: Check and build | |
| uses: nick-invision/retry@v2.4.0 | |
| with: | |
| max_attempts: 5 | |
| timeout_minutes: 15 | |
| command: | | |
| . venv/bin/activate | |
| make check | |
| export GITHUB_TOKEN=${{ github.token }} | |
| make build | |
| - name: Deploy branch preview | |
| if: github.event_name == 'pull_request' | |
| run: | | |
| BRANCH_NAME="${{ github.head_ref }}" | |
| SAFE_BRANCH=$(echo "$BRANCH_NAME" | sed 's/[^a-zA-Z0-9-]/-/g') | |
| . venv/bin/activate | |
| # Build with site_url set so navigation works in subdirectory | |
| cat > mkdocs-preview.yml << EOF | |
| INHERIT: mkdocs.yml | |
| site_url: https://docs.openworm.org/preview/$SAFE_BRANCH/ | |
| EOF | |
| python -m mkdocs build -f mkdocs-preview.yml --site-dir /tmp/site_preview | |
| # Push to gh-pages under preview/<branch>/ | |
| git fetch origin gh-pages:gh-pages | |
| git config user.name github-actions | |
| git config user.email github-actions@github.com | |
| git checkout gh-pages | |
| mkdir -p preview/$SAFE_BRANCH | |
| rm -rf preview/$SAFE_BRANCH/* | |
| cp -r /tmp/site_preview/* preview/$SAFE_BRANCH/ | |
| git add preview/$SAFE_BRANCH | |
| git commit -m "Deploy preview: $BRANCH_NAME @ ${GITHUB_SHA::7} [ci skip]" || echo "No changes to commit" | |
| git remote set-url origin https://${{ github.token }}@github.com/${{ github.repository_owner }}/openworm_docs.git | |
| git push origin gh-pages | |
| - name: Comment preview URL on PR | |
| if: github.event_name == 'pull_request' | |
| uses: actions/github-script@v7 | |
| with: | |
| script: | | |
| const branch = '${{ github.head_ref }}'.replace(/[^a-zA-Z0-9-]/g, '-'); | |
| const url = `https://docs.openworm.org/preview/${branch}/`; | |
| const marker = '<!-- preview-url -->'; | |
| const body = `${marker}\n**Preview:** ${url}`; | |
| const { data: comments } = await github.rest.issues.listComments({ | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| issue_number: context.issue.number, | |
| }); | |
| const existing = comments.find(c => c.body.includes(marker)); | |
| if (existing) { | |
| await github.rest.issues.updateComment({ | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| comment_id: existing.id, | |
| body, | |
| }); | |
| } else { | |
| await github.rest.issues.createComment({ | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| issue_number: context.issue.number, | |
| body, | |
| }); | |
| } | |
| - name: Archive production artifacts | |
| if: github.ref == 'refs/heads/master' | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: built-site | |
| path: site | |
| - name: mkdocs gh-deploy | |
| if: github.ref == 'refs/heads/master' | |
| run: | | |
| SHA="${{ github.sha }}" | |
| set -x | |
| git fetch origin gh-pages:gh-pages | |
| git config user.name github-actions | |
| git config user.email github-actions@github.com | |
| . venv/bin/activate | |
| mv $REPO_METADATA_SHAS $REPO_METADATA_SHAS.temp | |
| git checkout gh-pages | |
| cp $REPO_METADATA_SHAS.temp $REPO_METADATA_SHAS | |
| LAST_BUILT_SHA= | |
| if [[ -f ./last_build_sha ]] ; then | |
| LAST_BUILT_SHA=$(cat last_build_sha) | |
| fi | |
| if [[ "$LAST_BUILT_SHA" = "$SHA" ]] && git diff origin/gh-pages --exit-code $REPO_METADATA_SHAS ; then | |
| echo "No changes in repo metadata. Skipping deploy" | |
| else | |
| git checkout - | |
| ghp-import -o -n site | |
| git checkout gh-pages | |
| echo -n $SHA > last_build_sha | |
| git add last_build_sha | |
| mv $REPO_METADATA_SHAS.temp $REPO_METADATA_SHAS | |
| git commit --amend -m "Deploy master@$SHA [ci skip]" | |
| git remote set-url origin https://${{ github.token }}@github.com/${{ github.repository_owner }}/openworm_docs.git | |
| git push -f origin gh-pages | |
| fi | |
| cleanup-preview: | |
| if: github.event_name == 'pull_request' && github.event.action == 'closed' | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - name: Remove preview from gh-pages | |
| run: | | |
| BRANCH_NAME="${{ github.head_ref }}" | |
| SAFE_BRANCH=$(echo "$BRANCH_NAME" | sed 's/[^a-zA-Z0-9-]/-/g') | |
| git fetch origin gh-pages:gh-pages | |
| git config user.name github-actions | |
| git config user.email github-actions@github.com | |
| git checkout gh-pages | |
| if [ -d "preview/$SAFE_BRANCH" ]; then | |
| rm -rf preview/$SAFE_BRANCH | |
| git add -A preview/ | |
| git commit -m "Remove preview: $BRANCH_NAME [ci skip]" | |
| git remote set-url origin https://${{ github.token }}@github.com/${{ github.repository_owner }}/openworm_docs.git | |
| git push origin gh-pages | |
| fi |