Make documentation examples pass validation

Review 615 by @wmrowan
Closes #960