Diagram Creation Improvements

[modelmat]

I have been working on #220 and GraphViz is a massive PITA to work with.
Attempting to find an alternative that's not horrible. The existing sphinx-compatible alternatives are:

• PlantUML
  There is a reason why this wasn't used by @Daltz333 couldn't remember
• BlockDiag
  Requires too many dependencies
• GraphViz
  A PITA to work with

Some non-sphinx-compatible alternatives (non have sphinx extensions):

• Pic/Groff
  Is quite complex like GraphViz although it seems a less of a PITA
• draw.io
  This would allow for a GUI way of creating diagrams. It is also open-source and has a CLI tool that can convert from the diagrams into an image file. Unfortunately, the diagram files are XML with base64 encoded strings, but I believe the tradeoffs are worth it (easy GUI).

If anyone has any other suggestions for including diagrams in sphinx (preferably without having to create a sphinx extension, this would be nice.

[Daltz333]

I like the draw.io approach personally, the tradeoff is definitely worth it in terms of ease of development, and text-based alternatives are completely useless for visualizers anyways 🤷‍♂

[modelmat]

I made a quick sphinx extension for draw.io here.
It doesn't work on Linux atm (only on Windows) and may not work inside the CI (see jgraph/drawio-desktop#127).

[modelmat]

We could also use the Sphinx tikz extension.

[modelmat]

It appears that drawio should now work inside a docker container. It would most likely work inside of Azure too.
There is also draw-image-export2.

I still won't be able to confirm/work on this for a little while, hwoever.

[modelmat]

I have now have https://github.com/Modelmat/sphinxcontrib-drawio working in CI and it should be ready for use. There is also a unit test :)

[rickyjames35]

It appears that drawio should now work inside a docker container. It would most likely work inside of Azure too.
There is also draw-image-export2.

I still won't be able to confirm/work on this for a little while, hwoever.

@modelmat what was the solution to running drawio inside a docker container? I see there is a draw-image-export2 but I don't see a way to run it inside a docker container.

[ItayZiv]

It appears that drawio should now work inside a docker container. It would most likely work inside of Azure too.
There is also draw-image-export2.
I still won't be able to confirm/work on this for a little while, hwoever.

@modelmat what was the solution to running drawio inside a docker container? I see there is a draw-image-export2 but I don't see a way to run it inside a docker container.

We ended up running an Xvfb server to run draw.io CLI, there's a working version of this at https://github.com/Modelmat/sphinxcontrib-drawio for source code, but we don't use it since we cannot install draw.io on RTD, without very big complexity, so right now what we do is have svg files with embedded diagram metadata