Sankey diagram for need flow

[twodrops]

A Sankey Diagram is a visualization technique that allows to display flows. This will fit perfectly to show the traceability of needs and an alternate visualization to the current need-flow.

https://github.com/d3/d3-sankey would be a good option to implement this (provided a three-clause BSD license is acceptable for sphninx-needs).

[twodrops]

@danwos If this fits sphinx-needs and we can sketch the idea together, we can think about a contribution.

[danwos]

I like the idea of supporting Sankey diagrams and d3 and its extensions are great libraries.
But I would like to support the most common sphinx-outputs (at least HTML and PDF) and I have a bad feeling trying to reach this goal with a js-lib.
At least generating static files for PDF would mean to provide a working js-environment during a sphinx build.

Therefore I made a rough search on the internet for "Sankey diagrams the Python way":

• plotly sankey
• holoviews sankey (based on bokeh)
• matplotlib sankey

Plotly

For Plotly there is already a (quite new) sphinx integration:
https://pypi.org/project/sphinx-plotly-directive/

The content part of the .. plotly:: just takes pure plotly related python code.
So generating the needed Python code for a Sankey Diagram in sphinx needs and setting it as content for a Plotly-node should be doable. Sphinx-Needs uses the same approach for plantuml integration.

Also this would mean, that Sphinx-Needs is capable to support any plotly-feature in future.
So supporting other diagrams should be really easy after the initial implementation.

But I haven't tested anything right now. So if this sphinx-plotly extensions supports PDF output must still be checked.

Holoviews / Bokeh

Bokeh itself comes with a sphinx-extension and multiple directives:
https://docs.bokeh.org/en/latest/docs/reference/sphinxext.html#module-bokeh.sphinxext.bokeh_plot

Holoviews, which would provide the functions for a Sankey diagram, has nothing like this, but it claims that they are independent from the plotting implementation, so I guess the bokeh integration will work:
http://holoviews.org/user_guide/Plotting_with_Bokeh.html

But this I haven't used as well, so testing here is also needed.

matplotlib

matplotlib is already used for the pie chart diagrams in Sphinx-Needs.

However, the examples on their sankey-page does not match fully the ones from your example links.
But a google image searche looks promising.

So this should be the easiest implementation, with no new dependencies.
However, matplotlib diagrams are not interactive.
So I'm open to maybe replace it one day even for the pie-chart directive with plotly or holoviews/bokeh.

But I have technical concerns only and I'm not familiar with the needed functions and presentation forms of a Sankey diagram.
So if there is anything, which makes one of the above solutions your favorite, please let me know.

[twodrops]

Thanks for compiling this list. From the above, Plotly is my favorite. The static view of matplotlib is not very useful and also it has the age-old format for sankey. I will get back to you with a plan for contribution.

[twodrops]

I guess this issue can be handled as part of #392

[PhilipPartsch]

With the plotly directive https://pypi.org/project/sphinx-plotly-directive/ and matplotlib directive https://matplotlib.org/3.1.1/devel/plot_directive.html it is already wonderful possible to define customizable graps. Maybe we should provide a better documentation how to use these directive together with sphinx-needs.

[twodrops]

@PhilipPartsch How would you access need objects from those directives? The story is about having a better traceability diagram for sphinx-needs using some of these tools internally.

Now after several months of creating this issue I feel such reports should be part of an external tool like Grafana and not sphinx-needs. There is Sankey support in Grafana already https://grafana.com/grafana/plugins/netsage-sankey-panel/?plcmt=footer

Will be handled as part of useblocks/sphinx-needs-enterprise#8

@danwos I guess we can close this issue.