Self documentation - current state

@hynek @chadrik

I've tried following this and other threads and reading the current docs, but can't see if/how one best produces any documentation directly from the attr.ib() definitions.

If it does not exist, would something like argparse be a good example?
I suppose the type annotation (e.g. using attr.s(auto_attribs=True) is a step in the direction I am thinking/hoping for. I don't know the details, but Emacs does a good job of self-documenting, which is especially useful with the type annotation, as that provides at least some information for each argument.

Could someone point me in the right direction, please?

Start by reading the current documentation and the linked issue #104 and pull request #277, focusing on whether attr.ib() definitions or attr.s(auto_attribs=True) already expose enough information for generated documentation. Compare the desired behavior with argparse and the self-documenting behavior described for Emacs. Done means establishing the supported direction and documenting or specifying it clearly.