arrow
arrow copied to clipboard
apache
ARROW-17407: [Doc][FlightRPC] Flight/gRPC best practices
We want to provide best practices and debugging section in:
cpp flight docs python flight docs java flight docs R flight docs
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}
@rok Can we also add best practices and debugging sections in the Go docs too?
This can be done by either a README.md in the go/arrow/flight directory or by having a "package comment" in the directory (a comment directly above the package flight line in one of the .go files (convention is usually a file named doc.go).
Would you prefer for me to add it to this branch?
@rok Can we also add best practices and debugging sections in the Go docs too?
Thanks for chiming in @zeroshade! I was going to ask you where to put the Go specific content :). I'll add it and ping you back.
@rok Sounds great! Have a look at go/arrow/doc.go or go/parquet/doc.go for some examples.
https://tip.golang.org/doc/comment also gives a good rundown of how the format of the comment gets translated into the formatting of the rendered docs on pkg.go.dev (TL;DR it's similar to just using markdown)
@zeroshade I've added the Go doc. Please check if it makes sense, it's my first time touching Go docs.
@lidavidm I'm now linking to c++ from python/java/R docs which is not ideal, but duplicating text is not either. Any thoughts?
I'm now linking to c++ from python/java/R docs which is not ideal, but duplicating text is not either. Any thoughts?
IMO, I would think there should be a common area for the text since that is common across languages. Then, the c++ docs can include code snippets as appropriate which don't seem too relevant to the other languages.
The "Arrow Flight RPC" section under "Specifications and Protocols" seems like a good place to me, since those descriptions seem to be more related to best practices of using the protocol overall.
What's wrong with linking to the C++ docs?
The format/ page for Flight RPC is meant more for things all implementations agree on, I don't think these tips really go there
Also, linking to the C++ docs isn't applicable in all situations, they don't apply to Java for instance.
The same goes for Go.
If we want to centralize things, we should think about where to do that. And then all the language docs can link there. (I think Sphinx has a 'tabs' extension we could use for the language-specific snippets too.)
What's wrong with linking to the C++ docs?
I don't think there's anything wrong with it. I was just thinking through alternatives since Rok didn't seem to like it.
Also, linking to the C++ docs isn't applicable in all situations, they don't apply to Java for instance.
Maybe I misread that portion of the PR, but I think it references it at the moment? I don't know the details, so not sure if some of the descriptions need disentangling
The Java docs link to the C++ docs - but the C++ docs don't apply to Java. The bit about allocations doesn't apply to Java at all, for instance.
options that make the most sense to me are:
- make a new page, perhaps under the "development" section?
- leave the structure as is, and let a PR for ARROW-17378 and/or ARROW-6390 re-structure?
Maybe we should consider a separate tutorial section then? Even if they're language-specific? (Well, 'tutorials and guides' or something…) The Flight tutorials could probably be made to work with the same 'tab' structure so they can cover multiple languages at once (though that should be used sparingly)
Assuming this tab structure: I like the idea of a tab structure in cases where code snippets are small (or whatever text will go in the tabs), which seems to apply to what I see in this documentation. I also think that for something like flight, the focus is more on the protocol and communication so it's a case where there is a lot of conceptual overlap so tabs may work well here.
Otherwise, I don't have strong opinions about "best practices" being in, or separate from, a tutorial section.
Revision: 1c4b615d8ef1f99fe3a5d426a0a96d72d6771447
Submitted crossbow builds: ursacomputing/crossbow @ actions-703d0857cf
| Task | Status |
|---|---|
| preview-docs |  |
Revision: 81561aca202830f553973e6540a644f104a6cdc5
Submitted crossbow builds: ursacomputing/crossbow @ actions-6869e14038
| Task | Status |
|---|---|
| preview-docs |  |
@lidavidm @zeroshade I've addressed most of the feedback, you can see the rendered docs here: https://crossbow.voltrondata.com/pr_docs/13873/cpp/flight.html#best-practices
I'll be traveling until next Monday so feel free to either wait or finish this without me.
Revision: a6769e7fa5b8c5d11e0a87e172ecbe81fb3ab1ba
Submitted crossbow builds: ursacomputing/crossbow @ actions-15c34ca64d
| Task | Status |
|---|---|
| preview-docs |  |
I've addressed the feedback (hopefully all) and opened a cookbook issue (https://github.com/apache/arrow-cookbook/issues/251). Would appreciate another look! :)
Revision: f7692480997c03276f82a5a468fbc28fa4bf9532
Submitted crossbow builds: ursacomputing/crossbow @ actions-f012880c10
| Task | Status |
|---|---|
| preview-docs |  |
Thanks for the review @lidavidm ! I think I addressed everything and sorry for not being faster.