Publish API docs to GitHub pages#172
Conversation
Signed-off-by: Anuraag Agrawal <anuraaga@gmail.com>
Signed-off-by: Anuraag Agrawal <anuraaga@gmail.com>
stefanvanburen
left a comment
stefanvanburen
left a comment
There was a problem hiding this comment.
I'm +1 on having these here; makes sense to just link out to them from the connectrpc.com site. (Hopefully zensical doesn't ship too many breaking changes as they iterate 😄)
Can we perhaps add a justfile or similar target for running the docs locally? I could probably figure it out but we ought to make it easy to check.
docs/img/logo.svg
Outdated
There was a problem hiding this comment.
this seems to have issues rendering in GitHub, can we just double-check that it renders on the site?
There was a problem hiding this comment.
Oops yeah - had given it a try and gave up on it, forgot to delete
stefanvanburen
left a comment
stefanvanburen
left a comment
There was a problem hiding this comment.
great, happy to land this and iterate over time. Just dropping a few things I noticed from looking through the docs.
Looks like we're inconsistent in just a few places about ending our descriptions with periods; I think they all ought to end with one.
The description here leaks the type; not sure what's different but looks different from the others:
I imagine we can link stuff like modules even further with more syntax in our docstrings; not sure what zensical uses?
Lastly, I think we can probably add more context to some of the more complex types, like ConnectASGIApplication.endpoints, to say that this is generally passed directly from generated code from the plugin, or something to that effect.
Anyway, this is excellent as-is, thanks for reviving it.
Just a first pass at improving the rendering of some of these, based on the review I gave. Effectively: * Add periods consistently * Add some links * Mention generated code for endpoints (this maybe could be extended further?) * Make a couple docstrings more consistent with others I also noticed while iterating on this locally that `zensical serve` does not seem to consistently cache-bust when changing these docstrings; for now, I'm just wiping the cache as a part of the justfile target, and am planning to report upstream. Ref: #172 (review) Signed-off-by: Stefan VanBuren <svanburen@buf.build>
2 participants
When reviewing #84, I had actually completely forgotten wanting to not drop it at least without knowing how to handle API docs, which I think are helpful to have.
This restores only the API docs back for publishing to GitHub pages. I figure there's no practical way to integrate these into docusaurus so we can add a link to
https://connectrpc.github.io/connect-python/api/from the official docs. What do you think?