Add Newton review guidelines (#3922) #1258

Workflow file for this run

.github/workflows/docs-dev.yml at e7791e6

	name: Deploy dev documentation

	on:
	push:
	branches:
	- main
	workflow_dispatch:

	# Ensure only one deployment runs at a time
	concurrency:
	group: docs-deploy
	cancel-in-progress: false

	jobs:
	build-and-deploy:
	runs-on: ubuntu-latest
	permissions:
	contents: write
	steps:
	- name: Harden the runner (Audit all outbound calls)
	uses: step-security/harden-runner@fa2e9d605c4eeb9fcad4c99c224cee0c6c7f3594 # v2.16.0
	with:
	egress-policy: audit

	- name: Checkout repository
	uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
	with:
	fetch-depth: 1

	- name: Install uv
	uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
	with:
	version: "0.11.26"

	- name: Set up Python
	uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
	with:
	python-version-file: ".python-version"

	- name: Install pandoc
	uses: pandoc/actions/setup@86321b6dd4675f5014c611e05088e10d4939e09e # v1.1.1

	- name: Build Sphinx documentation
	# `-d docs/_build/doctrees` keeps Sphinx's pickled doctree cache out of
	# the published html/ tree (GH-2726): it is build-only state, ~25 MB of
	# non-deterministic bytes that no browser loads.
	run: uv run --extra docs --extra sim sphinx-build -j auto -d docs/_build/doctrees -b html docs docs/_build/html
	env:
	NEWTON_REQUIRE_PANDOC: "1"

	- name: Deploy to gh-pages /latest/
	run: \|
	set -e # Exit on any error

	git config user.email "actions@github.com"
	git config user.name "GitHub Actions"

	# Save built docs and 404 template outside the repo before switching branches
	mv docs/_build/html /tmp/docs-latest
	cp docs/_static/gh-pages-404.html /tmp/gh-pages-404.html

	# Switch to gh-pages branch (check existence first to avoid masking other fetch errors)
	# Distinguish "branch not found" (exit 2) from fatal errors (exit 128)
	# to prevent a transient failure from creating an orphan that overwrites
	# all existing versioned docs on the force push below.
	ls_remote_rc=0
	git ls-remote --exit-code --heads origin gh-pages > /dev/null 2>&1 \|\| ls_remote_rc=$?

	if [ "$ls_remote_rc" -eq 0 ]; then
	git fetch --depth=1 origin gh-pages:gh-pages
	git checkout gh-pages
	elif [ "$ls_remote_rc" -eq 2 ]; then
	echo "Creating new gh-pages branch"
	git checkout --orphan gh-pages
	git rm -rf . \|\| true
	else
	echo "::error::git ls-remote failed with exit code $ls_remote_rc — aborting to prevent data loss"
	exit 1
	fi

	# Remove old /latest/ and replace with new build
	rm -rf latest
	mv /tmp/docs-latest latest

	# Deploy custom 404 page for redirecting old non-versioned URLs
	cp /tmp/gh-pages-404.html 404.html

	# Ensure .nojekyll exists
	touch .nojekyll

	# Check gh-pages size (warn if approaching GitHub Pages 1GB limit)
	SIZE_KB=$(du -sk --exclude=.git . \| cut -f1)
	SIZE_MB=$((SIZE_KB / 1024))
	echo "Current gh-pages size: ${SIZE_MB}MB"
	if [ "$SIZE_MB" -gt 800 ]; then
	echo "::warning::gh-pages branch is ${SIZE_MB}MB, approaching GitHub Pages 1GB limit. Consider pruning old versions."
	fi

	# Stage new/modified files. git checkout --orphan below preserves the
	# full index from gh-pages, so all previously tracked files (e.g.
	# versioned release docs) are also included in the deploy commit.
	git add latest 404.html .nojekyll

	# Reset to an orphan commit to prevent unbounded history growth.
	# gh-pages is a deployment target, not a historical record.
	git checkout --orphan gh-pages-deploy
	git commit -m "Deploy dev docs from main@${GITHUB_SHA::8}"
	git push origin HEAD:gh-pages --force

Navigation Menu

Uh oh!

Add Newton review guidelines (#3922) #1258

Workflow file

Add Newton review guidelines (#3922) #1258

Uh oh!

Workflow file for this run