add ability to generate Markdown and HTML documenation; complete the example spec in more detail