Hi!
There are a lot of apps and plugins that use PlantUML scripts to draw all kinds of diagrams (sequence, state, class, object, component, activity, etc).
I think it would be great to be able to write PlantUML markup scripts in the comments for the doc generator, to include automatically the image of the diagram in the HTML.
For example:
proc foo(...) =
## Bla bla bla...
##
## @startuml
## participant User
##
## User -> A: DoWork
## activate A #FFBBBB
##
## A -> A: Internal call
## activate A #DarkSalmon
##
## A -> B: << createRequest >>
## activate B
##
## B --> A: RequestCreated
## deactivate B
## deactivate A
##
## A -> User: Done
## deactivate A
## @enduml
(...)
PNG generated for the HTML doc: http://www.plantuml.com/plantuml/png/LO_12eCm38RlUOh0phw0IB5EX5qtniwXvY3MrgLnpxywXMaE2U7_ylEdJagYo-HXpdDmmqn1yPbO0DQEXK5ROXjVKKOWfyE7bD7YfUkQN01sHsv1MG9vTEJzYMn9nWVvAOQTRagiAdJ26RZpU-6aQCp_9hisM6osktxzmJtqVA0EYzsSryXhsi1d4MeEVVxo2m00
If you like PlantUML diagrams you can create them online here: http://www.planttext.com
This is the reference guide of PlantUML language: http://plantuml.com/PlantUML_Language_Reference_Guide.pdf
And this is the PlantUML text encoding for the web service:
http://plantuml.com/server.html
Well at least it is nothing totally esoteric: https://en.wikipedia.org/wiki/PlantUML .. you may just add the PNGs to an asset directory such that generating the docs just creates ne ones if their code changes.
EDIT: Of course it would be much better if at least some Nim/C version would exist :)
Araq, I agree that it's not a good idea to depend on other tools, but in this case is not necessary to install anything, you only need to be online when you create the docs, and now everybody has an Internet connection. ; )
As you can see in the example I posted, PlantUML has an online server, just send the script as a simple HTTP GET request and you get the PNG/SVG:
http://plantuml.com/server.html
So, when you create the docs the compiler could check if there are PlantUML scripts in the comments, in that case, send the scripts to the server and get the images to insert in the HTML files. And in the case that you are offline (and there are PlantUML scripts), the compiler could output a warning. It'd be like an extra feature of the doc generator.
If you want to be sure that the server is always online is possible to install a PlantUML server (plantuml.war (less than 6MB)) and use it as a fallback server if the main server is temporarily offline.
OderWat, Yes, that's what I do, I create the PNGs to include in the docs as images but I've been thinking about creating a tool to post-process the HTML files to update the PNGs automatically.
you only need to be online when you create the docs
This sounds like a downright horrible idea. Compiler as a service? Hell no!
everybody has an Internet connection
This is not true in quite some corporate environments, if you use your laptop on top of your lap in a train, if you are in China and the URL is blocked, …
If you want to be sure that the server is always online is possible to install a PlantUML server (plantuml.war (less than 6MB))
plantuml.war, hm? So, these 6MB must be installed onto a 600MB Java application server, which is a resource hog and a pain to administrate.
Nothing stops you from generating a diagram with some external tool as part of your build process and then link it into your documentation (e.g. as SVG via .. image::). As UML diagrams usually give an overview and do not relate to one specific proc, the case where you want to include UML directly in the API documentation is rather rare. I'd rather place it on some overview page.