Add a state diagram to the documentation

[medihack]

Something similar to https://github.com/timgit/pg-boss/blob/master/docs/readme.md#job-states

[ewjoachim]

Note: we can do it with Mermaid, Myst supports it (so does Github Flavored Markdown)

[ewjoachim]

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 raw vs svg, 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 :)

[medihack]

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").

[ewjoachim]

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

[medihack]

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.

[medihack]

Closed by #1208