diff --git a/AGENTS.md b/AGENTS.md index 702d602..f911243 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,6 +22,8 @@ - Public website and user documentation: https://unftp.rs - Doctave (https://github.com/Doctave/doctave) is currently used to build the website - Website documentation lives in `docs/` and is done in markdown. +- Netlify is used for hosting and it is set up to deploy the "netlify" branch. +- A Makefile target called "site" will compile the docs and add it to the netlify branch ## Commit messages diff --git a/Makefile b/Makefile index 09a7d5d..3e48481 100644 --- a/Makefile +++ b/Makefile @@ -78,28 +78,8 @@ site-preview: # Previews the documentation for Github Pages and Netlify doctave serve .PHONY: site -site: # Publishes to the documentation to Netlify - doctave build --release - @if [ ! -d "site" ]; then \ - echo "Error: site directory not found after build"; \ - exit 1; \ - fi; \ - current_branch=$$(git branch --show-current); \ - site_tar=$$(mktemp -t site-XXXXXX.tar.gz); \ - tar -czf $$site_tar -C site .; \ - if git show-ref --verify --quiet refs/heads/netlify; then \ - git checkout netlify; \ - else \ - git checkout -b netlify; \ - fi; \ - find . -mindepth 1 -maxdepth 1 ! -name '.git' -exec rm -rf {} + 2>/dev/null || true; \ - tar -xzf $$site_tar; \ - rm -f $$site_tar; \ - git add -A; \ - git commit -m "Update documentation site" || true; \ - git push origin netlify; \ - git checkout $$current_branch; \ - rm -rf site +site: # Publishes the documentation to Netlify + @./scripts/publish-site.sh .PHONY: clean clean: # Removes generated files diff --git a/README.md b/README.md index a500525..c78cc9b 100644 --- a/README.md +++ b/README.md @@ -109,6 +109,16 @@ If you want to preview the docs: - Install Doctave as explained in the README at https://github.com/Doctave/doctave - Run `make site-preview` +To publish the documentation, merge your changes, update your local +`master`, and ensure it has no uncommitted tracked changes. Then run +`make site`. +This requires Doctave and permission to push to the `netlify` branch. The +publishing script builds the site, commits the generated files on that +branch, and pushes it; Netlify then deploys unftp.rs. +The script keeps your `master` checkout and its untracked files intact. If it +fails after building, it leaves `site/` for inspection; move or remove that +directory before retrying. + ## License You're free to use, modify and distribute this software under the terms of the Apache-2.0 license. diff --git a/scripts/publish-site.sh b/scripts/publish-site.sh new file mode 100755 index 0000000..432b01c --- /dev/null +++ b/scripts/publish-site.sh @@ -0,0 +1,67 @@ +#!/bin/sh +# Build the Doctave site and push its generated files to the netlify branch. +# Run from an up-to-date master with: make site +# Requires Doctave and permission to push to origin/netlify. Netlify deploys +# that branch to unftp.rs; this script does not call the Netlify API. +set -eu + +repo_root=$(CDPATH='' cd "$(dirname "$0")/.." && pwd) +cd "$repo_root" + +if [ "$(git branch --show-current)" != master ]; then + echo "Error: publish the site from master after merging documentation changes" >&2 + exit 1 +fi +if ! git diff --quiet || ! git diff --cached --quiet; then + echo "Error: commit or discard tracked changes before publishing" >&2 + exit 1 +fi + +site_dir="$repo_root/site" +if [ -e "$site_dir" ] || [ -L "$site_dir" ]; then + echo "Error: site directory already exists; move it before publishing" >&2 + exit 1 +fi + +# Publish only the current master. Fetch first so a stale source checkout or +# missing deployment branch fails before Doctave creates any files. +git fetch origin master +if [ "$(git rev-parse HEAD)" != "$(git rev-parse FETCH_HEAD)" ]; then + echo "Error: update master from origin before publishing" >&2 + exit 1 +fi +git fetch origin netlify +doctave build --release +if [ ! -d "$site_dir" ]; then + echo "Error: site directory not found after build" >&2 + exit 1 +fi + +# Keep the source checkout intact. The temporary worktree starts at the +# fetched deployment commit, so a concurrent remote update rejects our push. +site_worktree=$(mktemp -d) +cleanup() { + status=$? + trap - 0 + if ! git worktree remove --force "$site_worktree" >/dev/null 2>&1; then + rmdir "$site_worktree" 2>/dev/null || + echo "Warning: remove temporary worktree $site_worktree manually" >&2 + fi + exit "$status" +} +trap cleanup 0 + +git worktree add --detach "$site_worktree" FETCH_HEAD +git -C "$site_worktree" rm -r -q -- . +cp -R "$site_dir/." "$site_worktree/" +git -C "$site_worktree" add -A + +if git -C "$site_worktree" diff --cached --quiet; then + echo "Documentation site is already up to date" +else + git -C "$site_worktree" commit -m "Update documentation site" + git -C "$site_worktree" push origin HEAD:refs/heads/netlify +fi + +# Retain the generated site on failure for inspection or a retry. +rm -r "$site_dir"