Documentation lagging behind?

There are a few pieces of public functionality that are not properly documented yet.

For example:

• async with syntax for the AsyncClient (see #342) — I’ll push a PR for this soon.
• Request/response streaming (should probably part of the Advanced Usage section).
• Basic/Digest/Custom authentication (only the auth parameter is documented in the Developer Interface, but there’s no usage guide).

This issue is more to strike a discussion about how we should handle documenting features as they are merged into master.

Including documentation as part of the PR has been working very well for me in the past, although it does increase the amount of content to review. The main reason is that in general it’s hard to provide the initial documentation for a feature we did not implement ourselves.

Something we could keep in mind is to ask ourselves “does this require a documentation update?” for each PR. Maybe setting up a PR template with a comment hinting at this could do the trick? Of course, there’s the concern of raising the barrier for contributors, but someone has to update the docs anyway, so…

Thoughts @encode/httpx-maintainers and all?

[florimondmanca]

So, I don’t think this issue is very actionable in itself so I’d be in favor of closing it for housekeeping purposes. At least I think we agreed on this: let’s keep in mind that documentation changes should be part of a PR that touches anything publicly exposed. 😃

[yeraydiazdiaz]

I’d prefer requiring documentation changes as part of the PR, I feel I could forget otherwise (and indeed I have forgotten with the Digest auth).

If maintainers feel the PR is being delayed we can offer help or maybe push commits with small fixes.