Interleave doctest examples w/ API ref docs.

[tseaver]

Closes #1141

See my rationale for this implementation

[dhermes]

How to review this? Why ditch :members: and :undoc-members:?

[tseaver]

The PR trades off removing some DRY (the :members: and particularly :undoc-members:, which should arguable be excluded in any case) in exchange for getting control over the generation of the API docs (ordering, plus the ability to interleave the doctest examples in the Sphinx docs, with the promise of future testability).

It also makes the API docs more suitable for addition of exposition by non-programmer techwriters.

[dhermes]

But how do we make sure we haven't left anything out (the time-honored "check yourself (programatically) before you wreck yourself")?

[dhermes]

@tseaver Why do we consider this closed?

UPDATE: Oh duh it's a PR. So much fail!!