Hi!

I completely dropped the ball on this and I apologize for that, I got sidetracked by other things and forgot about this.

I will try to integrate this into cattrs soon as the last thing I do before releasing the next version.

In particular, is there a place for demo code that will be executed?

I assume you mean is the code in the documentation tested? We use doctests extensively so those can be used for this purpose. I don't insist on them though.

Should I add tests to verify that the behaviour I am describing in the docs is really what happens?

If you feel like they'd be valuable and feel confident enough to write them. Otherwise I'd skip em.

I'm not sure how to run the doctests, particularly in the docs/ directory.

I believe our tox setup can run the docs. Otherwise, I go into the docs directory and run make doctest.