procrastinate
procrastinate copied to clipboard
procrastinate-org
Add a state diagram to the documentation
Something similar to https://github.com/timgit/pg-boss/blob/master/docs/readme.md#job-states
I gave it a shot and it's a bit annoying:
- If we don't compile the mermaid graph when building the doc (a.k.a
raw):- We won't know if there's a syntax error at build time
- Actually, even as I'm trying to do that, Mermaid won't say what the syntax error is Oo
- (and it will be probably trickier for some doc users though probably a very small proportion who don't consume the doc in the browser)
- if we compile it (a.k.a
svg)- Then we need node in the build (that's actually ok but probably a bit annoying)
- And also, the doc build is slower
- (and for some reason, I don't encounter the same issues in
rawvssvg, no idea why)
(also light/dark mode)
I'll post my branch as a starting point but I probably won't be spending more time on it until we know where we're going. That said, anyone willing to continue it, feel free :)
As cool as something like Mermaid is, our state chart isn't that difficult (and hopefully consistent as soon as we get the "aborting" state caused by me out again 😞). How about just creating it by hand with a SVG editor? In the SVG, we can also use CSS to support the light and dark modes. I can look into it for the v3 branch (then I don't have to include "aborting").
You're probably right. Let's say the question is whether we just intend to have a single graph or if we can think of other parts of the doc that could benefit from some of the graphs Mermaid supports. I don't see one right now but I'll keep a brain cell on that, and I'll try to filter actually useful ideas, not just useless but cool ones :D
I also gave it a shot using Mermaid but in raw mode, and I think it's quite pretty 🙂. I used the "neutral" theme, which looks ok in light and dark mode. I also put a legend below that describes the edges, making it more clear and not so bloated. The syntax error in your example came from [](), which I also did not manage to escape inside the graph (but it doesn't matter, IMHO). I built the graph in their playground, where error reporting is better. I prefer the raw mode because it is easier to build. Even the unrendered source of the graph is simple to understand.