Supporting Diagrams in GitHub Previews

[AlexanderLanin]

Displaying diagrams on GitHub Pages is straightforward, since arbitrary processing can be done during site generation.
But what about the pure GitHub view, such as browsing files or reviewing a PR?

Idea generation in progress!

Here is what we have so far:

• ✅ Draw.io
  Store .drawio.svg files in the repo. GitHub renders them natively in Markdown.

• ✅ Mermaid
  Supported in GitHub Markdown files (.md), GitHub issues and GitHub pull requests.
  (Also supported in .rst files? Needs verification.)

• 🔄 PlantUML via proxy server
  Embed images using links to an online or self-hosted PlantUML server:
  ![Diagram](http://www.plantuml.com/plantuml/png/...)
  ⚠️ Not suitable for sensitive content; depends on external availability.
  ⚠️ Only renders images from the main branch. When viewing other branches or PRs, rendered diagrams may be outdated or incorrect.

• 🔁 PlantUML with CI-generated SVGs/PNGs
  Auto-generate diagrams from .puml files in CI and:

  • ✏️ Commit to the same PR branch
    Append a commit to each PR that includes the updated .svg files — or enforce that the author generates them before submitting.

  • 📦 Commit to a separate branch/repo/cache
    Avoid cluttering the main branch by storing generated images elsewhere, e.g.:

    • a gh-pages branch
    • a dedicated diagrams branch
    • an external repository used as an image cache
    • GitHub Pages to serve images via raw URLs

[FScholPer]

If we have a solution which supports c4 we can use the diagrams also with traceability tooling: useblocks/sphinx-needs#1304. For example: https://diagrams.mingrammer.com/docs/nodes/c4

[FScholPer]

Also for mermaid c4 seems to be supported: https://c4model.tools/#visual-modelling-tools. But don't know how sphinx needs can be used to validate and trace.

[kalu-an]

Dear @AlexanderLanin , @FScholPer , great thoughts, let me give my ones,
Regarding PlantUML

• Honestly pluma looks since it want´s to overcome the drawback of simple text based diagram by introducing reuse like in a real arch modelling tool like Enterprise Architecture -> @FScholPer have you experience or do you know how mature it is. Would it be an option for SCORE?
• Case we don´t want to render our diagram on public server we could host our own in SCORE plantuml-server

Regarding PlantUML Theme

• Could be included with !include statement pointing to a url where the theme is stored
• could also be injected for every diagram rendered with PlantUML. I.e. all diagrams will apply the same style without effort for the user. What I don´t know is how sphinx-needs is using PlantUML @AlexanderLanin could you help out here

Regarding traceability

• It´s this covered with sphinx-needs -> needflow:: Traceability
• To my knowledge we need to know which software component is realizing a requirement, must this be done in an diagram?

Case c4 is wanted I could recommend struturizr developed and maintained by Simon Brown the c4 god-father.

• It´s input and output agnostic and could run in a docker container
• Everyone could visit the architecture via a server which SCORE could host
• Arch model is wirten in an DSL
• Not UML conform
• Diagram auto-layout (e.g. graphviz) and/or user-placement (like draw.io)

In general I highly appreciate to see that SCORE drives arch-as-docs approach. I´m open for every kind of solution and willing to contribute.

Let me know you want to continue?

[FScholPer]

Current state is if any of the requirements or the software interfaces are changed they have to be changed in the diagram also: https://eclipse-score.github.io/process_description/main/process_areas/architecture_design/architecture_getstrt.html. This means much overhead and time consuming manual work. My proposal would be to automate as much as possible in our process. Take a look here for an example diagram: https://eclipse-score.github.io/process_description/main/process_areas/architecture_design/_assets/architecture_modeling_example.html

[kalu-an]

Dear @FScholPer,
fully agree with "automate as much as possible". I.e. generate diagrams based on IF description. This is what sphinx-needs want to solve. Traceability, autogenerate diagrams for architecture and requirement coverage as well. Therefore PlantUML is used by sphinx-needs. Is my understanding correct?

---

Nevertheless here is the statement from @LittleHuba for communication FT (correct me if needed)

For diagrams in communication FT we want to show certain aspects and/or dedicated views. Therefore we have drawn our diagrams initially

with UMLet. For SCORE we want

1. transform existing UMLet (=.uxf ) files to PlantUML (.puml) files with public Server
2. translate form markdown (.md) to reStructuredText (.rst)

In the end feature Level documentation moves to score/score repo, components level stays in score/communication repo

---

Pluma and c4 was is discussed in the discussion #1304 you brought in.

Long story short
@FScholPer, @AlexanderLanin and @LittleHuba which approach do you suggest to follow?

My personal view: Stay with sphinx-needs, configure it in a way that all rendered diagrams apply the score-theme, case needed for security reasons set up a SCORE server for hosting plantuml. With this setup we could

• Autogenerate with sphinx-needs
• render user written puml files
• use puml syntax in md, rst and github comments/discussions e.g.
  • puml file server rendered
    
  • url encoded server rendered
    

[hoe-jo]

@kalu-an sounds reasonable for me