I'm creating a library, and I would like to provide a tutorial on how to use the library. Such a tutorial will contain code snippets as usage examples; therefore, I would like to test these snippets to make sure the code is correct.
How can I test examples in the documentation?
I'm thinking about some kind of interleaving documentation text with traditional unit tests, but all the ideas I've got seem to lack elegance. One option may be in adding phpdoc comments to tests and then somehow creating web/printable version of the source code. Another way may be in referencing pieces of tests from Markdown documents. Either way requires some kind of tool to put things together, and I would prefer to use an existing tool.
The library is in PHP, and it uses PHPUnit for tests, but I'm looking for inspiration regardless of the language.
(Note: I've posted this question on Stack Overflow originally, but it didn't fit well there.)