Support for UML via PlantUML & sphinxcontrib-plantuml

[n1ywb]

It would be totally awesome if readthedocs supported UML using the radical UML tool PlantUML and the Sphinx extension sphinxcontrib-plantuml.

PlantUML is the only UML tool I've ever used that I didn't hate, probably because it's not a GUI, you create UML diagrams using a straightforward textual language.

sphinxcontrib-plantuml lets you inline plantuml source code right in your .rst files. Here's a trivial sequence diagram.

.. uml::
    Obj1 -> Obj2: Hello, world
    activate Obj2
    Obj2 --> Obj1: Goodbye, cruel world
    deactivate Obj2

http://plantuml.sourceforge.net/
https://pypi.python.org/pypi/sphinxcontrib-plantuml

Here's a complete example in a Sphinx doc

[wraithan]

Unfortunately, plantuml is not in any of the package repos for ubuntu. Also it requires adding java to the stack (and figuring out which java runtime it likes the most) for those reasons I'm going to lean toward not adding plantuml support.

If it were a package that I could just apt-get install without having to find some PPA from some third party, it would be easier for me to accept.

[n1ywb]

PlantUML is just a jar file. It runs fine on Ubuntu with the default Ubuntu
JRE (that's what I'm using here).

(webdlmon-backend-ve)jeff@jlconsulting~/jlconsulting/clients/ucsd_anf/wavefront/doc
$ java -version
java version "1.7.0_21"
OpenJDK Runtime Environment (IcedTea 2.3.9) (7u21-2.3.9-0ubuntu0.12.10.1)
OpenJDK 64-Bit Server VM (build 23.7-b01, mixed mode)

On Thu, Jun 20, 2013 at 5:31 PM, Chris McDonald [email protected]:

Unfortunately, plantuml is not in any of the package repos for ubuntu.
Also it requires adding java to the stack (and figuring out which java
runtime it likes the most) for those reasons I'm going to lean toward not
adding plantuml support.

If it were a package that I could just apt-get install without having to
find some PPA from some third party, it would be easier for me to accept.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/407#issuecomment-19784736
.

73 de n1ywb

[wraithan]

Being just a jar file means I have to put it somewhere, tell it to dump its logs/etc other places, and do that all in chef so that I can rebuild the server easily, rather than just adding a package name to the current chef scripts.

[canercandan]

@wraithan anything change since then ?

[gmarchand]

@wraithan it will be very cool to add this feature : Diagram is easier to understand

[greglanthier]

+1

[ch3lo]

An alternative is to use the url passing the plantuml code as parameter

[agjohnson]

It seems nothing has changed since then, this still isn't a supported package by ubuntu and I'm not even seeing a PPA for this either.

I'm -1 on installing arbitrary packages from source, this isn't a high enough priority to play package manager for. Without someone maintaining this properly, it's bound to cause us a headache.

[tuomas2]

+1

[MantasVaitkunas]

+1

[agjohnson]

Github seriously needs a vote button :/ If you have nothing to add to this conversation, please refrain from pinging maintainers with +1 comments.

Nothing has changed here, there is still no maintained package that is easily installable on Ubuntu 14.04. As our time is limited, supporting something like this from source is near the bottom of our expansive list.

We'd be happy to consider support plantuml if anyone wants to take on maintaining a PPA for Ubuntu. At this point we don't have much time to spare.

[n1ywb]

PPA here https://launchpad.net/~isage-dna/+archive/ubuntu/plantuml

On Tue, Jan 26, 2016 at 11:46 AM, Anthony [email protected] wrote:

Github seriously needs a vote button :/ If you have nothing to add to this
conversation, please refrain from pinging maintainers with +1 comments.

Nothing has changed here, there is still no maintained package that is
easily installable on Ubuntu 14.04. As our time is limited, supporting
something like this from source is near the bottom of our expansive list.

We'd be happy to consider support plantuml if anyone wants to take on
maintaining a PPA for Ubuntu. At this point we don't have much time to
spare.

—
Reply to this email directly or view it on GitHub
#407 (comment)
.

73 de n1ywb

[MantasVaitkunas]

@agjohnson, what actions should be done by community to solve this issue? As I understand n1ywb provides PPA.

[agjohnson]

Feel free to open a PR at https://github.com/rtfd/readthedocs-docker-images for the base image

Note: we will begin testing against 16.04 soon, for it's April releast, so this PPA should be able to support 16.04 as well or we'll have to drop it when we do the upgrade.

[prikhi]

I'd love this too...

I've never used Docker, but maybe this link will help someone who has the knowledge to make a proper PR to the readthedocks-docker-images repo:

https://hub.docker.com/r/grieve/sphinx-plantuml/~/dockerfile/

[tuukkamustonen]

It looks like there is now debian package for stretch (debian testing): https://packages.debian.org/stretch/plantuml

@agjohnson Is it possible to use their package?

[timofurrer]

Ubuntu 16.10 has the plantuml package in their repos as well.

As far as I can tell you are only using LSD releases for your rtd docker images. However, would it be possible to add this package to the 16.04 installation? (via pinning or download & dpkg)

I think this would make some documentation even more awesome! 🍻

(I'd be willing to create a PR if you'd agree to the above suggestion ...)

[danwos]

For me it is not necessary to provide plantuml itself. It should be enough to make java available.

The sphinxcontrib.plantuml extension has a parameter called "plantuml", which defines the complete command to call plantuml (e.g. java -jar my_tools/plantuml.jar).

You could provide the plantuml.jar file inside the docs repository and set the plantuml config var inside conf.py like this
plantuml = 'java -jar %s' % os.path.join(os.path.dirname(__file__), "tools/plantuml.jar")

From the repository owners point of view it is not so nice to keep tools inside the repo, but it may be ok.
But for the rtd team, this solution would be more generic, as it does not support a specific tool. Instead it only makes java available and is therefore supporting additional java tools beside plantuml as well.

Does somebody see any drawbacks for this solution?

[petrjasek]

I've made a PR for docker images which installs plantuml from repos:
readthedocs/readthedocs-docker-images#17
any feedback on that?

[petrjasek]

ping @agjohnson

[tartarini]

@agjohnson
considering that the plantuml package is in the mainstream Ubuntu packages.
Is there any issue in just installing it in the rtd images?
Just adding the following in conf.py works for me in Ubuntu:

plantuml = '/usr/bin/plantuml -Djava.awt.headless=true '

this addition would be really appreciated!

[mcicolella]

Any news about this?

[humitos]

plantuml was already added to the latest docker build image (readthedocs/readthedocs-docker-images@7bedf54). Now, I think this will be available when that latest docker image goes to production. I'm reopening this issue since it's something that's going to happen... sometime :)

[jirikuncar]

@humitos is there any known timeline to know when the image with plantuml will be in production?

[humitos]

@jirikuncar I don't know. But now, there is an option in the yaml to select the build image you want to use. See readthedocs/readthedocs-build#33 and #3339

(that PR and the related ones to that option, will be merged soon)

[agjohnson]

Closing this as the latest image does have usable plantuml, our 18.04 image has an updated version and will be released soon.

[n1ywb]

Thank you, everybody, for this, especially @agjohnson for seeing it through after all these years. Today my cup runneth over.