Add auto-generated API documention

[bhrutledge]

Related to #635.

While reviewing #799, I was curious to see how the Sphinx docstring directives would actually render, and how it treats typehints. This PR wires all of that up via the sphinx-apidoc command. I then merged in the new/updated docstrings as an example.

I'm not expecting this to be merged as-is. It feels a bit exotic, and since the audience is primarily maintainers and contributors, I expect that they will generally opt for reading the code rather than the docs. However, I did find it to be a useful preview of the docstrings, and it helped me think about how to write/organize them.

Maybe this could live in a separate branch, rendered as a distinct version on ReadTheDocs (along with latest and stable)?

[sigmavirus24]

Why can't we add the intersphinx mapping for requests? It should be as simple as updating 280 to be

{
  "python": ("https://docs.python.org/", None),
  "requests": ("https://requests.readthedocs.io/", None),
}

See also: https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html

[bhrutledge]

I tried that, via:

intersphinx_mapping = {
    "python": ("https://docs.python.org/", None),
    "requests": ("https://docs.python-requests.org/en/latest/", None),
}

But it's not entirely working:

WARNING: py:class reference target not found: requests.models.Response

Via intersphinx-untangled, it seems that the documented reference is the public requests.Response, and even though that's the type hint, it's being resolved to the internal class definition.

[sigmavirus24]

Why can't we just use requests.models.Response? It's documented as that in the docs. Most people use requests.Response because the author wanted to re-export the world which was a bad idea anyway

[bhrutledge]

Why can't we just use requests.models.Response? It's documented as that in the docs.

Where do you see it documented that way? I only see https://docs.python-requests.org/en/master/api/#requests.Response.

[bhrutledge]

I went down the rabbit hole on this, with the end result being sphinx-doc/sphinx#9653.