WIP: Expand docs on unstructuring

[td-anne]

I ran into some confusing situations trying to unstructure some objects I had defined (#513 ) and it was suggested I create a PR clarifying the docs. This PR attempts to do this.

I should say, my understanding of how cattrs works, and of how cattrs is meant to be used, is a little shaky, so feedback on this documentation is highly welcome.

I am also totally new to cattrs development, so I'm not sure where anything goes. In particular, is there a place for demo code that will be executed? Should I add tests to verify that the behaviour I am describing in the docs is really what happens? I'm not sure how to run the doctests, particularly in the docs/ directory.

[Tinche]

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.