Page MenuHomePhabricator

Support diagrams on Phabricator and mediawiki.org
Open, LowestPublic

Description

Software diagrams (such as class diagrams, sequence diagrams, state machines etc.) are a great way of conveying architecture at a highly abstract level, but they are a chore to create so we don't use them much. There are various easy-to-use diagram generators / editors but even then uploading images, sharing sources etc. is way too much effort.

mediawiki.org and Phabricator should make use of some software to generate diagrams straight from wikitext in an easy-to-create, easy-to-edit way so they get used a little more in our projects. Some candidates:

For Phabricator, this would have to be a Remarkup extension maintained by us (upstream has removed dot support due to security concerns and is not interested in other diagram languages - T9408, T12285).

Event Timeline

Tgr created this task.Dec 26 2017, 3:59 AM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptDec 26 2017, 3:59 AM
Aklapper triaged this task as Lowest priority.Dec 26 2017, 8:19 AM
Harej added a subscriber: Harej.Jan 29 2018, 8:10 PM

If we're talking about something used by both MediaWiki and Phabricator, it sounds like what this calls for is a service with accompanying MediaWiki and Phabricator extensions to interface with the service.

Discourse integration would also be nice, so all our technical spaces can use the same diagram markup. Discourse has plugins for Mermaid and PlantUML although neither has much commit activity.

If we're talking about something used by both MediaWiki and Phabricator, it sounds like what this calls for is a service with accompanying MediaWiki and Phabricator extensions to interface with the service.

PlantUML works like that, there is a server component that you can host locally. Mermaid runs in the browser (which means users with JS disabled wouldn't see the graphs, although I'm sure it's not too hard to run it as a Node service). GraphViz has plenty web service wrappers and even a full-JS implementation.

The fact that this task says "on Phabricator and mediawiki.org" makes me want to close this as non-actionable. Two totally different and unrelated systems... :-/

Tgr added a comment.Jun 12 2020, 5:38 PM

How is that non-actionable? The action is trivially described by the title. Less manageable, maybe; OTOH it wouldn't be very useful to end up with non-compatible diagram notation syntax on the two primary platforms for discussing system architecture.

... makes me want to close this as non-actionable. Two totally different and unrelated systems... :-/

Maybe two subtasks for the two systems after a common notation is established.

It would be great to having a diagram generation tool on mediawiki.org. Of the three extensions listed, the Mermaid extension is the only one marked as stable, so I tried re-creating a few diagrams from mediawiki.org to see how Mermaid works.

Overall, I found Mermaid’s syntax to be fairly straightforward and easy to use. In my experiments, it worked best for decision trees, sequence diagrams, and simple-to-medium complexity flowcharts. Mermaid also has nice features that allow you to assign links to nodes, incorporate Font Awesome icons, and customize styling. If it’s possible to enable on mediawiki.org, I think the Mermaid extension would be a useful tool for improving documentation.

For example, this diagram of MediaWiki’s architectural modules could be replaced with a Mermaid version, replacing the complex imagemap and making the diagram easier to maintain. See this wikifarm page for a demo.

Source:

{{#mermaid:graph LR;
 index.php-->MediaWiki;
 MediaWiki-->Page;
 Page-->Action;
 Action-->ViewAction;
 ViewAction---id1{ };
 id1{ }-->Parser;
 id1{ }-->Cache;
 Cache-->OutputPage;
 Parser-->OutputPage;
 OutputPage-->Skin;

 classDef dottedOutline stroke-dasharray: 3, 3;
 classDef whiteFill fill:white;
 class ViewAction dottedOutline;
 class index.php,MediaWiki,ViewAction,OutputPage,id1,id2 whiteFill

 click index.php "https://www.mediawiki.org/wiki/Manual:Index.php"
 click MediaWiki "https://www.mediawiki.org/wiki/Manual:Architectural_modules/MediaWiki"
 click Page "https://www.mediawiki.org/wiki/Manual:Architectural_modules/Page"
 click Action "https://www.mediawiki.org/wiki/Manual:Architectural_modules/Action"
 click ViewAction "https://doc.wikimedia.org/mediawiki-core/master/php/classViewAction.html"
 click Parser "https://www.mediawiki.org/wiki/Manual:Architectural_modules/Parser"
 click Cache "https://www.mediawiki.org/wiki/Manual:Architectural_modules/Cache"
 click OutputPage "https://www.mediawiki.org/wiki/Manual:Architectural_modules/OutputPage"
 click Skin "https://www.mediawiki.org/wiki/Manual:Architectural_modules/Skin"
}}

Output:

To see more examples of diagrams from mediawiki.org re-created with Mermaid, see the slides from my presentation to the Friends of the Docs group on 2020-06-17.

Tgr updated the task description. (Show Details)Jun 21 2020, 4:22 PM
Tgr added a comment.Jun 21 2020, 4:28 PM

Thanks a lot for looking into this @apaskulin!

Extension stability does not mean much IMO, I would rather choose a solution based on the strength of the various markup languages + the tool used for rendering the image on the server side (which is something MediaWiki will just shell out to). We can fix up any of these extensions (or write a new one) without too much effort, they are really just scaffolding between the wiki and the (non-PHP) rendering server or library used.

Is comparing the other options (not necessarily the extensions, there are online tools like http://www.plantuml.com/plantuml/ and https://dreampuf.github.io/GraphvizOnline/ ) something you'd be interested in doing?