Automatically generate tutorial app from Markdown #2732
Conversation
Signed-off-by: Mihovil Ilakovac <[email protected]>
web/docs/tutorial/06-actions.md
Outdated
| } | ||
| ``` | ||
| </TabItem> | ||
| <TutorialAction step="8" action="diff"> |
There was a problem hiding this comment.
Just an idea, maybe not useful, but what we did for doc coderef checker is add this metadata directly tot he codeblock, via the "meta string", basically what follows in the line after three backticks and a language.
So you could do simlar, instead of having to add this extra copmonent around the code block, you could just have this, as part of the code block:
(three backticks)diff tutorial="#1"
you might not even need to supply any extra information at all, because based on the language you can figure out if you want to do diff or not. You can also obtain the file path from the title and for example if block is sh and has no title, you then execute it. That said, you can also be more explicit and just have a very simple dsl in the meta value string, something like tutorial="#<step>:<action>[:<action_param>]", for example tutorial="#1:write:src/main.wasp" or tutorial="#2:diff".
You will know the best if this is a good fit or not, maybe this kind of approach is not flexible enough, for example if you expect that there will be something that is not a code block that is also a part of the tutorial, but if all of it are code blocks, this might help with avoiding repeating some information + might make the DX a bit simpler / more integrated. Maybe it is worth doing this as the very last thing, once you have the system flushed out and have better idea what you need.
There was a problem hiding this comment.
I'd rename this to step-08 so that it gets ordered better :D
There was a problem hiding this comment.
Martin had a good suggestion to keep the step IDs as unique strings and not really ordered numbers. If we add a new step between step 5 and 6 then that changes all the subsequent IDs.
There was a problem hiding this comment.
Yes we concluded together it might be id that is also informative, so add-action or something. So path file's name would be "tutorial file name" + "step id".
web/tutorial/src/index.ts
Outdated
| await waspNew(appDir) | ||
| // TODO: Maybe we should have a whitelist of files we want to keep in src? | ||
| await $`rm ${path.join(appDir, 'src/Main.css')}` | ||
| await $`rm ${path.join(appDir, 'src/waspLogo.png')}` | ||
| await $`rm ${path.join(appDir, 'src/MainPage.jsx')}` |
There was a problem hiding this comment.
I guess this should be the "minimal" starter?
web/tutorial/package.json
Outdated
There was a problem hiding this comment.
Can't wait to move to npm workspaces, doing packages inside of packages inside of packages feels very brittle
web/tutorial/package.json
Outdated
There was a problem hiding this comment.
Can we get a readme of what this script does?
web/tutorial/src/edit/index.ts
Outdated
There was a problem hiding this comment.
What would you think about this workflow? Using git rebase machinery, we take advantage of automatic conflict resolution whenever it's possible.
Example: There are 10 steps, I want to edit step 4
User: (no edits made yet) $ edit-tutorial --step 4
Program:
- Create git repo, apply all 10 steps, one in each commit → (1)
git switch -c fixes $step4commitSHA
User: Makes changes as needed, tells program he's done
Program:
git commit -a --fixup=$step4commitSHA→ (2)git switch maingit rebase fixes→ (3)
User: completes the rebase process if there are any conflicts. Most conflicts get automatically resolved by git
Program
git rebase --root --autosquash→ (4)- Convert back from commits to patches
Deploying wasp-docs-on-main with
|
| Latest commit: |
3ea8530
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://2ba2b52d.wasp-docs-on-main.pages.dev |
| Branch Preview URL: | https://miho-tutorial-app-from-docs.wasp-docs-on-main.pages.dev |
infomiho
changed the title
Signed-off-by: Mihovil Ilakovac <[email protected]>
This PR implements running all the steps from the tutorial in the docs. We encode all the code changes into Git patches which we apply one by one.
We implement tooling for working with the patches when something breaks:
This PR doesn't try to use
git rebaseto correct errors in patches because I felt fast enough with doing the changes manually. Maybe I'm too deep in the tutorial code?