Feature request: Add blockdiag support

[moigagoo]

Hi! This is merely an idea, feel free to close and delete this issue if you think it doesn't make sense.

Currently, Needs uses PlantUML to draw diagrams. PlantUML requires Java, which makes it hard to use on remote machines you don't have control over (i.e. readthedocs).

However, there's a pure-Python alternative to PlantUML, natively supported in Sphinx (and even created by one of its core maintainers)—blockdiag.

Don't you think it would be a good idea to have blockdiag available as a backend for diagrams in Needs?

[danwos]

Ohh that's a great idea. I will check the lib and possible integrations the next days. But supporting different backends for diagram drawing would be awesome. Thanks for the feature request.

[moigagoo]

I'd love to contribute on that one. Unfortunately, I have very limited experience with Sphinx extension development and the developer docs for it are quite messy (oh the irony).

As far as I understand, here's what has to be done:

1. Add config value needs_diagram_engine that can be 'plantuml' or 'blockdiag'.
2. Add an if check for this value here: https://github.com/useblocks/sphinxcontrib-needs/blob/master/sphinxcontrib/needfilter.py#L108
3. Construct the blockdiag block similar to this https://github.com/useblocks/sphinxcontrib-needs/blob/master/sphinxcontrib/needfilter.py#L123. However, I don't understand why you're building an empty block (startuml followed by enduml).
4. Construct the actual blockdiag block similar to this https://github.com/useblocks/sphinxcontrib-needs/blob/master/sphinxcontrib/needfilter.py#L249
5. If show_legend is set, add description to the blockdiag block.

[danwos]

Your contribution is highly welcome and your description of the needed points is correct.

For 3: After a fast review I'm also not sure, if this empty block is really needed during node declaration.

However, your change would make the related function even more complex, as some more if statements get included. But that's OK for the moment. For one of the next version, we should do some refactoring and split this little monster of a function to higher the maintainability.

Please do not forget to describe the new possibilities inside our sphinx-docs and a test case is also highly appreciated :-)

[twodrops]

A related idea #162

[danwos]

I close this, as it would provide already existing features with another technical solution only.
So the benefit is quite small and the costs are too high.