Replace ASCII art with mermaid diagrams in WireGuard section#635
Replace ASCII art with mermaid diagrams in WireGuard section#635s-makin merged 8 commits intocanonical:mainfrom
Conversation
|
Thank you @s-makin :-) |
| 10.10.10.10-49 | ||
| ``` | ||
|
|
||
|
|
There was a problem hiding this comment.
This is that the rendering looks like:
The "pi4" box is on top of the network number on the top right.
There was a problem hiding this comment.
The connection between the router and the devices has changed in the mermaid diagram. Now it looks like each device is connected directly to the router, but that's not correct. True, the original ascii-art diagram was omitting this detail: there is usually a switch in the picture, but it's common to omit that as being "obvious", and the way the lines just blend together into one trunk line that goes into the router indicates that.
In other words, is there a way to have the lines from the devices merge together and only then connect to the router, somewhat what the original diagram was showing? Or do we need to add another box here to represent the switch, and then connect the switch via one single line to the router?
There was a problem hiding this comment.
Lastly, can the dotted line connecting home0 to wg0 be berhaps changed to a dashed line? The dots are too close together and look too similar to a full line.
There was a problem hiding this comment.
This is the updated rendering
| style internet fill:#C8E6C9 | ||
| style router fill:#FFE0B2 | ||
| style vpn fill:#BBDEFB | ||
| style home fill:#FFF9C4 |
There was a problem hiding this comment.
Contrary to the previous diagram, here we have a circle representing the vpn network, and boxes representing interface names. I realize now that we already had a box for wg0 in the previous diagram. Can these instead be labels on the lines, and placed close to the box where they physically are? Here, wg0 is an interface on the laptop on one hand, and an interface on the router. Each one with their own IP. Likewise, ppp0 could be placed closer to the box, and not something "in between".
Perhaps mermaid is not flexible enough for this: after all, it's meant for fluxograms, right?
There was a problem hiding this comment.
I've been fiddling with this for a while today and I can't seem to get any sort of control over the placement of the labels. Where they go seems to depend on where the renderer places all the other elements. The only way I think we'd be able to solve this is if we used block diagrams instead of flowcharts, with a bunch of invisible nodes.
There was a problem hiding this comment.
I've tried using a bunch of different types of diagrams - block diagrams, architecture diagrams, etc, and none of them provide a satisfactory result. I think Mermaid just isn't capable of producing what we're looking for here, however there will be an implementation of network diagrams in the future that seems to address the difficulties we're having. For that reason, I'll restore this diagram back to the ascii-art version, and we'll reopen the associated issues once the network diagrams have been implemented in Mermaid.
s-makin
force-pushed
the
manually-resolve-merge-conflicts
branch
from
45afe02 to
6ab0555
Compare
|
This turned out to be much more complicated than we initially thought, thanks to Mermaid not really supporting the sort of diagram we needed, but we got there in the end! Thanks for your patience and tenacity, @MariaBego56 - this is a huge improvement to the Server documentation! |
|
Hi @s-makin, I have to apologise, I have been AWOL. I have started a new job this week. The previius 3 weeks finishing my former job were extremely busy as I was trying to finish off all my projects so there wouldn't be any incomplete work left. I also wanted to tell yoy thank you for your work and the things I have learnt but for the foreseable future I eon't be able of being as active as I would like to. I wiah you a lovely weekend. Best regards, Maria |
Hi @MariaBego56 and thanks for letting me know. Congratulations on your new job! I hope that goes well for you :) In that case I will close the currently open PRs that were waiting for your response. If and when you feel able to finish those, send me a ping and we can re-open them. Thanks for all your efforts on our behalf, we really appreciate the contributions you've made! All the best! |
|
Hi @s-makin , PS I really liked the article you wrong explaining your use of AI and what you learnt. |
3 participants
Description
Unfortunately the original set of PR(s) that updated the ASCII art in the WireGuard section became quite complicated to merge due to a large number of conflicts with subsequent changes.
I have manually applied all of the changes proposed by @MariaBego56 onto a fresh/clean branch to avoid all of these conflicts, and it should be now good to merge.
The diagrams should now all be rendering correctly, and I have also fixed the issue that prevented RTD from building the 391 PR.
Thank you again, @MariaBego56 for creating these diagrams, and for all your patience as we worked through all the different build problems! Mermaid can be tricky, but we got there in the end.
Related Issue
Checklist