Skip to content
docs

Update docs infrastructure #21

Sign in to view logs

Update docs infrastructure

Update docs infrastructure #21

Workflow file for this run

.github/workflows/docs.yml at 6a3049e
name: docs
on:
push:
branches:
- master
paths:
- 'doc/**'
pull_request:
branches:
- master
paths:
- 'doc/**'
workflow_dispatch:
permissions:
contents: read
jobs:
# These first jobs will run regardless of whether the PR branch is from ESCOMP/CTSM or a fork.
test-build-makefile:
if: ${{ always() }}
name: Test building documentation with makefile
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
lfs: true
- name: Install python 3.x
uses: actions/setup-python@v2
with:
python-version: '3.x'
# https://github.com/actions/cache/blob/main/examples.md#python---pip
- name: Cache pip
uses: actions/cache@v3
with:
path: ~/.cache/pip
key: ${{ runner.os }}-pip-${{ hashFiles('doc/requirements.txt') }}
restore-keys: |
${{ runner.os }}-pip-
- name: Install dependencies
run: |
pip install -r doc/requirements.txt
# Build documentation under ${PWD}/_build
- name: Build Sphinx docs with makefile
run: |
make SPHINXOPTS="-W --keep-going" BUILDDIR=${PWD}/_build -C doc/ html
test-doc-builder:
if: ${{ always() }}
name: Test building documentation with doc-builder
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
lfs: true
- name: Install python 3.x
uses: actions/setup-python@v2
with:
python-version: '3.x'
# https://github.com/actions/cache/blob/main/examples.md#python---pip
- name: Cache pip
uses: actions/cache@v3
with:
path: ~/.cache/pip
key: ${{ runner.os }}-pip-${{ hashFiles('doc/requirements.txt') }}
restore-keys: |
${{ runner.os }}-pip-
- name: Install dependencies
run: |
pip install -r doc/requirements.txt
# Build documentation under ${PWD}/_build
- name: Build Sphinx docs with doc-builder
run: |
cd doc && ./build_docs -b ${PWD}/_build -c
# The following jobs will only run if the PR branch is in ESCOMP/CTSM, not a fork.
cleanup:
permissions:
contents: write # for git push
name: Cleanup branch previews
runs-on: ubuntu-latest
if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.event.pull_request.head.repo.full_name == github.repository
steps:
- uses: actions/checkout@v3
with:
ref: 'gh-pages'
fetch-depth: 0
lfs: true
path: gh-pages
- name: Remove branch previews
run: |
pushd $GITHUB_WORKSPACE/gh-pages
if [[ -e "$GITHUB_WORKSPACE/gh-pages/branch" ]]; then
ls -la "$GITHUB_WORKSPACE/gh-pages/branch"
for name in `ls branch/`
do
if [[ -z "$(git show-ref --quiet ${name})" ]]
then
git rm -rf branch/${name}
echo "Removed $GITHUB_WORKSPACE/gh-pages/branch/${name}"
fi
done
git config user.name github-actions[bot]
git config user.email github-actions[bot]@users.noreply.github.com
git commit -m "Clean up branch previews"
git push
fi
echo "Done cleaning branches"
build-and-deploy:
permissions:
contents: write # for peaceiris/actions-gh-pages to push
pull-requests: write # to comment on pull requests
needs: cleanup
if: github.event.pull_request.head.repo.full_name == github.repository
name: Build and deploy documentation
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
lfs: true
- name: Install python 3.x
uses: actions/setup-python@v2
with:
python-version: '3.x'
# https://github.com/actions/cache/blob/main/examples.md#python---pip
- name: Cache pip
uses: actions/cache@v3
with:
path: ~/.cache/pip
key: ${{ runner.os }}-pip-${{ hashFiles('doc/requirements.txt') }}
restore-keys: |
${{ runner.os }}-pip-
- name: Install dependencies
run: |
pip install -r doc/requirements.txt
# Build documentation under ${PWD}/_build
- name: Build Sphinx docs
run: |
make SPHINXOPTS=-W --keep-going BUILDDIR=${PWD}/_build -C doc/ html
- name: Push PR preview
if: |
github.event_name == 'pull_request' &&
github.event.pull_request.head.repo.full_name == github.repository
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{secrets.GITHUB_TOKEN}}
publish_dir: './_build/html'
destination_dir: './branch/${{ github.event.pull_request.head.ref }}/html'
user_name: 'github-actions[bot]'
user_email: 'github-actions[bot]@users.noreply.github.com'
- name: Comment about previewing documentation
if: |
github.event_name == 'pull_request' &&
github.event.pull_request.head.repo.full_name == github.repository
uses: actions/github-script@v6
with:
script: |
const comments = await github.paginate(github.rest.issues.listComments, {
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number
});
const havePosted = comments.map(x => x.user.login).some(x => x === "github-actions[bot]");
if (!havePosted) {
await github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: 'You can preview documentation at https://escomp.github.io/ctsm/branch/${{ github.event.pull_request.head.ref }}/html/index.html'
})
}
# - name: Push new docs
# if: ${{ github.event_name == 'push' }}
# uses: peaceiris/actions-gh-pages@v3
# with:
# github_token: ${{secrets.GITHUB_TOKEN}}
# publish_dir: './_build/html'
# destination_dir: './versions/master/html'
# user_name: 'github-actions[bot]'
# user_email: 'github-actions[bot]@users.noreply.github.com'