[boxed]

In the docs for iommi we've tried both the documentation-centric and the code-centric approaches.

We started with the documentation-centric approach because we had a lot of documentation and wanted to check if the code examples in them worked. So I wrote a bad parser that extracted the code from rST and put them into python files that we then ran. This worked... ok-ish.

Then we switched to the code-centric approach that we use today where we write tests that we generate the documentation from. There are specially marked documentation strings plus some tags for parts of the tests that shouldn't be included in the generated documentation, and some other cool little features like saving down the output of test requests to their own html files and then embedding them with iframes instead of using screenshots.

I am a programmer so I like the code-centric approach more, but they are pretty similar. The big thing is that you need to control the file format/parser yourself.