Skip to content
documentation

Add SPLASH project to README.md #387

Sign in to view logs

Add SPLASH project to README.md

Add SPLASH project to README.md #387

Workflow file for this run

.github/workflows/docs.yml at 07419e2
# Build the documentation and deploy to GitHub Pages using GitHub Actions.
#
# NOTE: Pin actions to a specific commit to avoid having the authentication
# token stolen if the Action is compromised. See the comments and links here:
# https://github.com/pypa/gh-action-pypi-publish/issues/27
#
name: documentation
# Only build PRs, the main branch, and releases. Pushes to branches will only
# be built when a PR is opened. This avoids duplicated buids in PRs comming
# from branches in the origin repository (1 for PR and 1 for push).
on:
pull_request:
push:
branches:
- main
release:
types:
- published
# Use bash by default in all jobs
defaults:
run:
shell: bash
jobs:
#############################################################################
# Build the docs
build:
runs-on: ubuntu-latest
env:
REQUIREMENTS: env/requirements-build.txt env/requirements-docs.txt
steps:
# Cancel any previous run of the test job
# We pin the commit hash corresponding to v0.5.0, and not pinning the tag
# because we are giving full access through the github.token.
- name: Cancel Previous Runs
uses: styfle/[email protected]
with:
access_token: ${{ github.token }}
# Checks-out your repository under $GITHUB_WORKSPACE
- name: Checkout
uses: actions/checkout@v4
with:
# Need to fetch more than the last commit so that setuptools-scm can
# create the correct version string. If the number of commits since
# the last release is greater than this, the version still be wrong.
# Increase if necessary.
fetch-depth: 100
# The GitHub token is preserved by default but this job doesn't need
# to be able to push to GitHub.
persist-credentials: false
# Need the tags so that setuptools-scm can form a valid version number
- name: Fetch git tags
run: git fetch origin 'refs/tags/*:refs/tags/*'
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: "3.x"
- name: Collect requirements
run: |
echo "Install Dependente to capture dependencies:"
python -m pip install dependente==0.3.0
echo ""
echo "Capturing run-time dependencies:"
dependente --source install,extras > requirements-full.txt
echo ""
echo "Capturing dependencies from:"
for requirement in $REQUIREMENTS
do
echo " $requirement"
cat $requirement >> requirements-full.txt
done
echo ""
echo "Collected dependencies:"
cat requirements-full.txt
- name: Get the pip cache folder
id: pip-cache
run: |
echo "::set-output name=dir::$(pip cache dir)"
- name: Setup caching for pip packages
uses: actions/cache@v4
with:
path: ${{ steps.pip-cache.outputs.dir }}
key: ${{ runner.os }}-pip-${{ hashFiles('requirements-full.txt') }}
- name: Install requirements
run: |
python -m pip install --requirement requirements-full.txt
- name: List installed packages
run: python -m pip freeze
- name: Build source and wheel distributions
run: |
make build
echo ""
echo "Generated files:"
ls -lh dist/
- name: Install the package
run: python -m pip install dist/*.whl
- name: Build the documentation
run: make -C doc clean all
# Store the docs as a build artifact so we can deploy it later
- name: Upload HTML documentation as an artifact
uses: actions/upload-artifact@v4
with:
name: docs-${{ github.sha }}
path: doc/_build/html
#############################################################################
# Publish the documentation to gh-pages
publish:
runs-on: ubuntu-latest
needs: build
if: github.event_name == 'release' || github.event_name == 'push'
steps:
- name: Checkout
uses: actions/checkout@v4
# Fetch the built docs from the "build" job
- name: Download HTML documentation artifact
uses: actions/download-artifact@v4
with:
name: docs-${{ github.sha }}
path: doc/_build/html
- name: Checkout the gh-pages branch in a separate folder
uses: actions/checkout@v4
with:
ref: gh-pages
# Checkout to this folder instead of the current one
path: deploy
# Download the entire history
fetch-depth: 0
- name: Push the built HTML to gh-pages
run: |
# Detect if this is a release or from the main branch
if [[ "${{ github.event_name }}" == "release" ]]; then
# Get the tag name without the "refs/tags/" part
version="${GITHUB_REF#refs/*/}"
else
version=dev
fi
echo "Deploying version: $version"
# Make the new commit message. Needs to happen before cd into deploy
# to get the right commit hash.
message="Deploy $version from $(git rev-parse --short HEAD)"
cd deploy
# Need to have this file so that Github doesn't try to run Jekyll
touch .nojekyll
# Delete all the files and replace with our new set
echo -e "\nRemoving old files from previous builds of ${version}:"
rm -rvf ${version}
echo -e "\nCopying HTML files to ${version}:"
cp -Rvf ../doc/_build/html/ ${version}/
# If this is a new release, update the link from /latest to it
if [[ "${version}" != "dev" ]]; then
echo -e "\nSetup link from ${version} to 'latest'."
rm -f latest
ln -sf ${version} latest
fi
# Stage the commit
git add -A .
echo -e "\nChanges to be applied:"
git status
# Configure git to be the GitHub Actions account
git config user.email "github-actions[bot]@users.noreply.github.com"
git config user.name "github-actions[bot]"
# If this is a dev build and the last commit was from a dev build
# (detect if "dev" was in the previous commit message), reuse the
# same commit
if [[ "${version}" == "dev" && `git log -1 --format='%s'` == *"dev"* ]]; then
echo -e "\nAmending last commit:"
git commit --amend --reset-author -m "$message"
else
echo -e "\nMaking a new commit:"
git commit -m "$message"
fi
# Make the push quiet just in case there is anything that could leak
# sensitive information.
echo -e "\nPushing changes to gh-pages."
git push -fq origin gh-pages 2>&1 >/dev/null
echo -e "\nFinished uploading generated files."