Mkdocs Makefile (before I realised it already *does* all that stuff on its own)

Makefile

TITLE = Lyrion.org documentation tasks
SHELL = bash
PYTHON = python3
VIRTUALENV = venv
REQUIREMENTS = mkdocs-requirements.txt
OUTPUTDIR = site
BINDADDR = 127.0.0.1
PORT = 8888

help:  # prints this help
	@perl -e "$$AUTOGEN_HELP_PL" Makefile

build: pipinstall  # build the documentation site
	mkdocs build

serve: venvactive $(OUTPUTDIR)/sitemap.xml # serve the documentation site locally [try BROWSE=1]
ifneq ($(BROWSE)$(BROWSER),)
	$(PYTHON) -m webbrowser -t http://$(BINDADDR):$(PORT) &
endif
	$(PYTHON) -m http.server --directory=$(OUTPUTDIR) --bind=$(BINDADDR) $(PORT)

clean:  # removes the documentation output directory
	-rm -r $(OUTPUTDIR)

pipinstall: venvactive
	pip install -r $(REQUIREMENTS)

venvactive: venv
	@if [[ "$$(type -p $(PYTHON))" == "${PWD}/$(VIRTUALENV)/bin/$(PYTHON)" ]]; then \
		echo "Virtual environment '$(VIRTUALENV)' is active. Good." >&2; \
		exit; \
	else \
		echo "Virtual environment not active." >&2; \
		echo "Run '. $(VIRTUALENV)/bin/activate' to activate it." >&2; \
		exit 1; \
	fi

# sets up a Python virtualenv (if you don't have one)
venv:
	@if [[ ! -f venv/bin/activate ]]; then \
		$(PYTHON) -m venv $(VIRTUALENV) || exit 1; \
		echo "Created virtual environment at '$(VIRTUALENV)'." >&2; \
		echo "Run '. $(VIRTUALENV)/bin/activate' to activate it." >&2; \
	fi

##
##  internals you can safely ignore
##
define AUTOGEN_HELP_PL
# line 47
	if (-t 1) {
		$$UL = "\e[0;4m"; $$BOLDBLUE = "\e[1m\e[1;34m"; $$RESET = "\e[0m";
	}
	$$max = 0;
	@targets = ();
	print "\n  ", $$UL, "Makefile targets - $(TITLE)", $$RESET, "\n\n";
	while (<>) {
		push @targets, [$$1, $$2] if /^(\w.+):[^=].*#\s*(.*)/;
		$$max = length($$1) if length($$1) > $$max;
	}
	foreach (@targets) {
		printf "    %smake %-$${max}s%s    %s\n", $$BOLDBLUE, @$$_[0], $$RESET, @$$_[1];
	}
	print "\n";
endef
export AUTOGEN_HELP_PL

Mkdocs' serve already runs a build and does live reload; it also has a -o option to open the browser when finished. But here's a good technique that would work with some other static site generator (Pandoc!) without those batteries included.