clients: overhaul docs generation #1417
Conversation
|
The end state I am aiming at with this stack of PRs: |
| @@ -0,0 +1 @@ | |||
| Code from README collected into a single runnable project. | |||
There was a problem hiding this comment.
Maybe link to the README that is being referred to (since this file is also a README).
There was a problem hiding this comment.
since this file is also a README
🤦
| const section_end = self.sprintf("endsection:{s}\n", .{section_name}); | ||
|
|
||
| var text = self.walkthrough; | ||
| for (0..10) |_| { |
There was a problem hiding this comment.
If I'm reading this right, if there are multiple sections with the same name, then this concatenates them all together, is that right?
There was a problem hiding this comment.
Correct! This is used for java, which, for the first, imports example, needs to concatenate public static void main(String[] args) { with the } at the end of file.
added a comment!
matklad
force-pushed
the
matklad/docs-generate-II
branch
from
59ad9da
to
80a7440
Compare
|
😩 docker:
Amusingly, googling this error turns up some results from January last year! |
These samples just collect code from README.md into on runnable project. The idea is that we will _generate_ README from this sample project. As a side effect, readme gets tested through the usual samples-testing infra.
The "walkthorough" sample is now validated together with all the other samples.
matklad
force-pushed
the
matklad/docs-generate-II
branch
from
80a7440
to
ab99986
Compare
|
Ok, for some reason, re-running the job didn't work, but rebasing the whole branch did the trick. |
|
Wait, somehow, after a rebase, the review is not dismissed? 🤔 this seems like a new behavior... |
I noticed that too! I wonder what the heuristic is for whether or not the approval is retained. |
TL;DR: turn the logic for generating client readmes upside down --- rather than assambling a readme sample out of code fragments from docs.zig, write the entire readme sample as a proper sample in the samples directory, and inject fragments of that sample into the readme.
Motivation: right now, we have two completely different code paths for integration-testing our client samples:
clients.yamlon CI.This PR reconciles the two approaches, by making sure that the code from README is just a sample. This also has auxilary benefits:
I tried to change as little as possible, as the diff here is large anyway. I do plan to send a significant cleanup PR as a follow up: for example, I believe the entirety of shutil.zig and run_with_tb.zig is now dead code.
That said, there's a bunch of user-visible changes here already:
{on a line by itself.try-with-resourcesversion, I don't think we should advertise bad practicies, and it was simpler to just drop this altogether, rather than add it to walkthroughs.npm install tigerbeetle-nodeandnode main.js. Now, these are not tested. I think this is fine --- these are upstream stable interfaces which are not going to change. We might have some bugs there, but the cost of such bug feels small, and they are unlikecly to reappear after they are repaired.