Nat Pryce has an interesting idea for maintaining code samples in API documentation. The gist is that the examples are maintained as programs in same source control repository as the API itself. This allows them to be tested and kept sync with the evolving API. Special markup is used in the program to write the prose and explanations. From the source code a HTML-document is generated that shows the prose and the actual program. While a reader navigates the explanations one by one, only the current explanation is shown, which reduces the clutter and guides the reader through the program step by step.
I think this is pretty nifty tool. Especially the ability to test the examples is important in order to keep them in sync with the code. My approach has been using Sphinx + DocTest as shown in pyherc – documentation.