Sphinx-Needs and PlantUML C4

[danwos]

The idea is to use Sphinx-Needs to model a Software Architecture and be able to

• reuse SW Architecture elements in different views
• get a technical readable architecture model for further checks/tests

Use cases

• Document SW architecture (what else ;))
• Check code changes against a defined SW Architecture
• Link requirements and maybe tests against SW Architecture elements

Status quo

Sphinx-Needs

• Sphinx-Needs has already diagram support peer need.
• Sphinx-Needs has needuml to combine own PlantUML code with reused diagrams from Need objects.

PlantUML

• There are multiple libraries that extend PlantUML to support a specific kind of SW Architecture definition (DSL)
  • PlantUML-C4, which is using PlantUML to paint diagrams for the C4 model
  • pumla extends the above solution, by adding a reusable concept on top of it.

There are plenty of other Architecture-as-code solutions out there. But as Sphinx-Needs is already using PlanUML and generating PlantUML-specific code for a need, implementing C4 could be quite easy.

What's the difference to the existing "arch-support" in Sphinx-Needs?

The current implementation is quite open and allows any kind of representation and data interpretation.

The PlantUML-C4 model needs a strict syntax and has predefined elements and views. This makes it easy to use and write common docs.

What's the idea

• Provide predefined Sphinx-Needs types and options, which cover the C4 model
• Provide a needc4 directive, which is able to paint with the help of PlantUML-C4 the different views based on given needs/filters.
• Some kinds of exporters, to
  • Get the generated views as PlantUML diagrams
  • Get a technical representation of the SW Architecture

I guess this all should be a new Sphinx extension, like Sphinx-Test-Report.

Any feedback on this idea? :)

[chrisjsewell]

yep, my feedback would be; don't use plantuml 😅
I don't see anything here that cannot be achieved just using graphviz.
In fact, https://github.com/mingrammer/diagrams is a good example of this; just building on top of graphviz with a python API

[danwos]

I was afraid you say that. But after reading the linked docs and figuring out that there is already a C4 implementation, I totally agree.

So anything against using https://github.com/mingrammer/diagrams as a drawing backend? For sure in the moment in a sphinx extension only. I'm still not sure where the best place would be.

[ubmarco]

I think we should also support free graphing with tools such as drawio. Then find a way to annotate diagram parts so we can extract them technically. There are diagram types that are hard to make with as-code tooling. I've also heard of people doing architecture that are not so much into as-code.

[danwos]

Agree, but it's a different use case for me. This proposal is more about a ready-to-use, well-defined method to define architecture in Sphinx-Needs. For sure, there can be other ways as well.