Add source build documentation (#319) #268

	name: "Sphinx: Publish docs"

	on:
	pull_request:
	branches:
	- "**"
	paths:
	# Only run for changes to this workflow file
	# (docs-preview workflow covers actual docs changes)
	- ".github/workflows/docs.yml"
	push:
	branches:
	- main

	# Require explicit job permissions
	permissions: {}

	jobs:
	build:
	runs-on: ${{ matrix.os }}
	strategy:
	# Not actually a matrix build, but defined as one for consistency
	max-parallel: 1
	matrix:
	python-version: [3.12]
	os: [ubuntu-latest]
	permissions:
	# Allow updating the gh-pages branch
	contents: write

	# Check https://github.com/actions/action-versions/tree/main/config/actions
	# for latest versions if the standard actions start emitting warnings
	steps:
	- uses: actions/checkout@v4
	with:
	persist-credentials: false

	- name: Build HTML
	# https://github.com/ammaraskar/sphinx-action/releases/tag/8.2.3
	uses: ammaraskar/sphinx-action@54e52bfb642e9b60ea5b6bcb05fe3f74b40d290a
	with:
	docs-folder: "docs/"
	pre-build-command: "sphinx-build -W -b linkcheck . _build"
	build-command: "sphinx-build -W -b dirhtml . _build"

	- name: Deploy main docs
	# https://github.com/JamesIves/github-pages-deploy-action/releases/tag/v4.7.3
	uses: JamesIves/github-pages-deploy-action@6c2d9db40f9296374acc17b90404b6e8864128c8
	if: github.ref == 'refs/heads/main'
	with:
	token: ${{ secrets.GITHUB_TOKEN }}
	folder: docs/_build/
	branch: gh-pages
	# CNAME and .nojekyll are left alone by default
	clean-exclude: pr-preview
	force: false

Provide feedback