search

encode / httpx

A next generation HTTP client for Python. 🦋
https://www.python-httpx.org/
BSD 3-Clause "New" or "Revised" License
13.24k stars 839 forks source link

Improve the API Reference #397

Closed thebigmunch closed 4 years ago

thebigmunch commented 5 years ago

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.

sethmlarson commented 5 years ago

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.

florimondmanca commented 5 years ago

I used pydocmd in 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.

tomchristie commented 5 years ago

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.

tomchristie commented 5 years ago

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 commented 4 years ago

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.