Improve the API Reference

From the README: “The Developer Interface provides a comprehensive API reference.”.

I’ll be blunt: I’m not even sure its useful in its current form, let alone comprehensive. The API reference is always my pathway to learning a library. Much knowledge was just inherited/assumed from requests. Most of the rest I’ve gone to the code for. To be fair, this isn’t a major hassle for me; I like code diving. But all users aren’t like me. Prose docs are good for some things and up to a point. But many times, what someone needs is best handled by a good API reference.

I love mkdocs. I much prefer it for most parts of documentation to Sphinx. And I know mkdocs2 may become a thing in the future, but that’s too far out.

I know its been discussed at least a bit in the 1.0 blockers issue, but I think the API reference/autodoc story is a much bigger deal than that. So that’s my reasoning for opening this issue.

So, my question is… are there any suggestions/constraints on a possible way forward on httpx’s API reference/autodoc story in the near future? I haven’t yet played with pydoc-markdown, but that may be one reasonable way.

[tomchristie]

I think the light touch approach that’ll be worth looking into here will be seeing if I can adapt the docstring markdown plugin I was working on for mkdocs2 can instead simply be built for the existing mkdocs package. I may try to find some time in October to take this on.

[florimondmanca]

Hi there,

Not that there’s not anything actionable in this issue, but since we’ve got some docstring-based docs infrastructure in place already I’ll close this for housekeeping — would be great to see more of those though.