Repository navigation
Improve the API Reference #397
Description
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.
Activity
sethmlarson commentedon Sep 26, 2019
I agree that section of the documentation is in need of some love, especially for descriptions of behaviors beyond the function signature.
I'm going to defer to @tomchristie or others for a solution here, I've only worked with Sphinx myself.
[-]API Reference[/-][+]Improve the API Reference[/+]florimondmanca commentedon Sep 27, 2019
I used
pydocmdin the past myself, in particular for the Bocadillo API reference. See Responses as an example. It's a very much OK Markdown-based API generator. It's got some quirks (for example, putting links in parameter descriptions is sometimes tricky, and I don't think it handles cross-referencing yet), but overall it can do a pretty good job.In any case, I think switching to a documentation method that's as close as possible to the code (i.e.: in docstrings) can only be beneficial, as it makes it much easier to develop the API reference and keep it in sync with the actual behavior.
I think there's plenty of room for non-code contributions in HTTPX, and contributing docs is definitely one of them.
lovelydinosaur commentedon Sep 27, 2019
The low-touch approach to this as an interim measure would be to duplicate in two places.
It's not ideal but it could be sufficient just to get started.
An altenative would be for me to work on a markdown plugin to add support for this to the existing mkdocs, which seems like it could be a pretty big win.
Most important thing from my POV is that whatever we're doing needs to also be consistent across other encode projects - so eg. switching away from mkdocs just isn't feasible, but supplementing or adapting it can be.
lovelydinosaur commentedon Oct 1, 2019
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 commentedon Mar 25, 2020
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.