Move documentation to use `sphinx.ext.autodoc` or `sphinx-apidoc`

[pradyunsg]

Currently, our various classes are described in the documentation via explicit .. class .. method directives. We should move to autodoc, and move these docstrings inline.

This will reduce the duplication, and make it difficult for the documentation to be out-of-sync with the code.

[uranusjr]

In my unfortunate experience, third-party (inclouding contrib) API discoverer eventually become a source of sorrow since they are generally slower (than autodoc) to pick up new Python syntax e.g. type annotation, keyword-only arguments. I’d suggest sticking with autodoc.

[brettcannon]

I personally have not historically loved using the docstrings as the canonical docs because you end up either with overly verbose docstrings that no longer serve their intended purpose of fast and simple docs at your fingertips in the REPL, or you keep them short but then your bigger docs lack details. Plus I hate listing parameters in docstrings when type annotations tell you everything anyway. 😜

Now, having said that, our docs have that opening section explaining what things are for, the code examples, and our API isn't overly complicated (just what it has to do 😉). So maybe it's not too much of a concern for our docs.

[pradyunsg]

FWIW, I think our API isn't particularly different in complexity compared to installer -- and I quite like the approach I'd taken there w.r.t. the API documentation presentation and generation. I'm definitely biased though, since that documentation webpage is almost completely filled with my design opinions. 😅

https://installer.readthedocs.io/en/stable/

[brettcannon]

We can give it a shot and if it doesn't work we can always pull the docs back out.

[pradyunsg]

Fair enough, and sounds like a plan! And, based on what @uranusjr said, autodoc it is. :)