wake-up-neo.com

So integrieren Sie UML-Diagramme in GitLab oder GitHub

Ich möchte einige Programmierdokumentationen veröffentlichen, die ich in einem öffentlich zugänglichen Repository habe. Diese Dokumentation enthält formatierten Text, einige UML-Diagramme und viele Codebeispiele. Ich denke, dass GitHub oder GitLab gute Orte sind, um dies zu veröffentlichen.

Um die UML-Diagramme zu veröffentlichen, möchte ich eine einfache Möglichkeit haben, sie im Repository zu aktualisieren und als Bilder im Wiki sichtbar zu machen. Ich möchte die Diagramme nicht in meinem Computer (oder in der Cloud) aufbewahren, sie bearbeiten, ein Bild generieren und dann jedes Mal veröffentlichen.

Gibt es eine Möglichkeit, die Diagramme im Repository abzulegen (in PlantUML-Syntax wäre ideal), sie mit dem Markdown-Text zu verknüpfen und die Bilder jedes Mal automatisch aktualisieren, wenn das Diagramm aktualisiert wird?

gitgithubumlmarkdowngitlab
43
joanq

Nachdem ich die andere Antwort ausprobiert hatte, stellte ich fest, dass der Dienst langsam ist und scheinbar nicht der neuesten Version von PlantUML entspricht.

Ich habe einen anderen Weg gefunden, der nicht ganz so einfach ist, aber er funktioniert über den Server von PlantUML.com (in der Cloud). Als solches sollte es funktionieren wo immer Sie einen Hotlink zu einem Bild haben können. 

Es nutzt die !includeurl-Funktion und ist im Wesentlichen eine Indirektion. Die Markdown-Datei enthält eine Verknüpfung zu einer PlantUML-Quelle, die die Quelle des Diagramms enthält. Mit dieser Methode können Sie die Quelle in GitHub ändern. Bilder in den GitHub-Markdown-Dateien werden automatisch aktualisiert. Es ist jedoch ein schwieriger Schritt, um die URL für die Indirektion zu erstellen.

Diagram of how it works

  1. Rufen Sie die URL zur rohen PlantUML-Quelle ab, z. B. https://raw.githubusercontent.com/linux-china/plantuml-Gist/master/src/main/uml/plantuml_Gist.puml (anhand des Beispiels in der Antwort von joanq).

  2. Gehen Sie zu http://plantuml.com/plantuml/form (oder PlantText.com) und erstellen Sie eine einzeilige PlantUML-Quelle, die die Operation !includeurl URL-TO-RAW-PLANTUML-SOURCE-ON-GITHUB verwendet. Wenn Sie mit der Beispiel-URL fortfahren, lautet die Quelle für PlantUML (Meta):

    !includeurl https://raw.githubusercontent.com/linux-china/plantuml-Gist/master/src/main/uml/plantuml_Gist.puml

  3. Kopieren Sie die Bild-URL von PlantUML.com das Bild, zum Beispiel http://plantuml.com:80/plantuml/png/FSfB2e0m303Hg-W1RFPUHceiDf36aWzwVEl6tOEPcGGvZXBAKtNljW9eljD9NcCFAugNU15FU3LWadWMh2GPEcVnQBoSP0ujcnS5KnmaWH7-O_kEr8TU und fügen Sie ihn in Ihre GitHub Abschlags-Datei. Diese URL wird nicht geändert.

    ![PlantUML model](http://plantuml.com:80/plantuml/png/3SNB4K8n2030LhI0XBlTy0YQpF394D2nUztBtfUHrE0AkStCVHu0WP_-MZdhgiD1RicMdLpXMJCK3TC3o2iEDwHSxvNVjWNDE43nv3zt731SSLbJ7onzbyeF)

Bonus: Sie können sogar auf das SVG-Format zugreifen, indem Sie den plantuml/png/-Teil der URL wie folgt plantuml/svg/ ändern

![PlantUML model](http://plantuml.com:80/plantuml/svg/3SNB4K8n2030LhI0XBlTy0YQpF394D2nUztBtfUHrE0AkStCVHu0WP_-MZdhgiD1RicMdLpXMJCK3TC3o2iEDwHSxvNVjWNDE43nv3zt731SSLbJ7onzbyeF)

Beispiel für GitHub

https://github.com/fuhrmanator/course-activity-planner/blob/master/ooad/overview.md

Edit: Alternative mit Proxy-Dienst

Dieser Weg ist wesentlich anders und einfacher als die Antwort oben. Es verwendet den PlantUML-Proxy-Service :

http://www.plantuml.com/plantuml/proxy?src=https://raw.github.com/plantuml/plantuml-server/master/src/main/webapp/resource/test2diagrams.txt

Der GitHub-Abschlag dafür wäre:

![alternative text](http://www.plantuml.com/plantuml/proxy?src=https://raw.github.com/plantuml/plantuml-server/master/src/main/webapp/resource/test2diagrams.txt)

Bei dieser Methode kann das SVG-Format nicht angegeben werden (standardmäßig PNG), und es ist möglicherweise nicht möglich, den in den Kommentaren erwähnten Zwischenspeicherungsfehler zu umgehen. 

41
Fuhrmanator

Ich habe festgestellt, dass dies mit plantuml-Gist unter http://uml.mvnsearch.org/ möglich ist.

Fügen Sie einfach eine gültige Puml-Datei in das Repository ein und fügen Sie einen Link zu dieser Site in die Dokumentation ein.

Für die Datei https://github.com/linux-china/plantuml-Gist/blob/master/src/main/uml/plantuml_Gist.puml in GitHub würden Sie beispielsweise http:/verwenden. /uml.mvnsearch.org/github/linux-china/plantuml-Gist/blob/master/src/main/uml/plantuml_Gist.puml als Link.

So sieht es aus, wenn es in StackOverflow verlinkt ist: 

UML-Image http://uml.mvnsearch.org/github/linux-china/plantuml-Gist/blob/master/src/main/uml/plantuml_Gist.puml

Leider scheint es nicht mit GitLab zu funktionieren. Ich bekomme immer ein "Keine PUML-Datei gefunden", obwohl ich den Pfad mehrmals überprüft habe.

EDIT: Server bei uml.mvnsearch.org scheint ausgefallen zu sein.

11
joanq

Dies ist eine alte Frage, die jedoch früh bei der Suche nach Lösungen für dieses Problem auftaucht.

In den anderen Antworten wird GitHub erörtert. Beachten Sie jedoch, dass GitLab die native Integration dafür aufweist, wenn Sie die interne Bereitstellung durchführen. Aus irgendeinem Grund haben sie die Funktion in ihrem öffentlichen Angebot nie aktiviert. Es gibt Tickets offen , um die Funktion zu aktivieren.

Wenn Sie mit einer intern gehosteten Lösung arbeiten, finden Sie Anweisungen in der Verwaltungsdokumentation.

Im Grunde du 

  1. stellen Sie Ihren eigenen Plantuml-Server auf
  2. Überprüfen Sie den Enable PlantUml in der GitLab-Serverkonfiguration
  3. schreiben Sie PlantUml in Ihren Markdown
```plantuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
```
1
Jefferey Cave