Add support for documenting instance attributes

[florimondmanca]

Suggested in https://github.com/encode/httpx/pull/464#issuecomment-541045025

Preview:

self.auth = auth
self._params = QueryParams(params)
self._headers = Headers(headers)
self._cookies = Cookies(cookies)
self.max_redirects = max_redirects
#: The dispatcher.
#: A second line of comments.
self.dispatch = async_dispatch
self.concurrency_backend = backend

Things still TODO:

• Handle case when attribute is assigned multiple times (right now the attribute will be displayed multiple times, but we want it to be displayed only once, i.e. the first time it is encountered).
• Add tests.

Notes:

• I used #: (which is what sphinx uses) instead of # because users may want to write regular comments and not have them interferring with generated docs.
• I used autodoc-signature/docstring for classes because IMO instance attributes should render consistently with other members — is this sound?
• Should we support reading the description from an inline #: comment? (Probably a followup issue.)
• With this PR, properties would be rendered just like than public instance attributes. This makes me think we may want to support more fine-grained rendering for properties, e.g. add a property marker and document whether it is read-only (no setter).
• Sphinx supports reading the attribute description from a class attribute. I guess we could consider a variant of it in the future (read from a type annotation, e.g. useful for namedtuples).

import typing

class Point(typing.NamedTuple):
    #: The x coordinate.
    x: int
    #: The y coordinate.
    y: int

[tomchristie]

I used #: (which is what sphinx uses) instead of # because users may want to write regular comments and not have them interferring with generated docs.

I reckon we should probably just roll with the standard comments. It's not an unreasonable constraint to introduce, and it's more easily discoverable.

Should we support reading the description from an inline #: comment?

Nah - let's keep it simple & consistent. (Also that's way harder to guess-parse correctly)

Sphinx supports reading the attribute description from a class attribute. I guess we could consider a variant of it in the future

Yeah that'd be a reasonable follow-up.

With this PR, properties would be rendered just like than public instance attributes. This makes me think we may want to support more fine-grained rendering for properties

Yeah I don't know. A property marker is probably a nice addition, in line with eg. async markers. I reckon we could just leave set/get descriptiveness for the developer to deal with in the docstring wording.

[florimondmanca]

I reckon we should probably just roll with the standard comments. It's not an unreasonable constraint to introduce, and it's more easily discoverable.

Any thoughts on resorting to docstrings placed above the attribute assignment, instead of comments?

[thebigmunch]

Any thoughts on resorting to docstrings placed above the attribute assignment, instead of comments?

Generally tools and documentation styles (e.g. Google) use the convention of docstring follows the thing being documented. I use the Google style with sphinx-napoleon currently to document module-level variables this way. Some use/most support the preceding comment (with your suggested #: syntax) as well.

I reckon we should probably just roll with the standard comments. It's not an unreasonable constraint to introduce, and it's more easily discoverable.

I think a standard comment and a comment meant as a docstring should be separate, as is done with current tooling. A comment meant for a contributor is not the same as documentation for a user.

[pawamoy]

I would personally prefer to use docstrings rather than comments for class variables or instance attributes documentation. This is what docstrings are used for.