docs

Switch to pyproject.toml for package configuration #177

Summary
Jobs
- build
- publish
Run details
- Usage
- Workflow file

Workflow file for this run

	# 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: docs

	# 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:
	# The -l {0} is necessary for conda environments to be activated
	# But this breaks on MacOS if using actions/setup-python:
	# https://github.com/actions/setup-python/issues/132
	shell: bash -l {0}

	jobs:
	#############################################################################
	# Build the docs
	build:
	runs-on: ubuntu-latest
	env:
	REQUIREMENTS: env/requirements-docs.txt env/requirements-build.txt
	PYTHON: "3.10"

	steps:
	# 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@v4
	with:
	python-version: ${{ matrix.python }}

	- 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 > 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: 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: pip install --no-deps dist/*.whl

	- name: Cache the downloaded datasets
	uses: actions/cache@v2
	with:
	path: ${{ runner.temp }}/.cache/pooch
	# Use a constant key to reuse the datasets across all jobs
	key: pooch

	- 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@v2
	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@v2
	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."

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Switch to pyproject.toml for package configuration #177

Workflow file

Switch to pyproject.toml for package configuration #177

Jobs

Run details

Workflow file for this run