Document plantuml usage

[agjohnson]

Document how to use sphinxcontrib-plantuml with RTD.

Because X11 isn't exposed through docker, java needs to be called in headless mode. Heck, we can likely set this in our conf.py template as well, so that users have the correct config.

To get it to work, you'll need:

plantuml = 'java -Djava.awt.headless=true -jar /usr/share/plantuml/plantuml.jar'

Also, you need to run the latest image.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[danwos]

Thanks for providing the needed plantuml command :+1:

The extension Sphinx-Needs is using plantuml for some stuff and I have just added an installation section how to use it for rtd: https://sphinxcontrib-needs.readthedocs.io/en/latest/installation.html#install-plantuml

If I find some time, I'll write the needed docs. But unfortunately not in the next days.

So here is the text as screenshot. For the latest version (and text to copy) see link above.

[CThuleHansen]

I cannot seem to get this to work on readthedocs since I get the error: ModuleNotFoundError: No module named 'sphinxcontrib.plantuml' when it is building on rtd

[stsewd]

@CThuleHansen you need to install the extension on rtd, see https://docs.readthedocs.io/en/stable/guides/specifying-dependencies.html

[CThuleHansen]

@stsewd thank you! It works now.

[danwos]

Java (and therefore plantuml) seems to be not installed, when using the build-commands feature. I'm also not allowed to use apt-get to install it.

The "apt_packages" config option seems not to be taken into account.

[humitos]

Hi @danwos! You are correct. build.commands does not support using build.apt_packages yet. I'm not sure it will be supported in the future since the idea of build.commands is to not run anything on behalf of the user. I'd assume that we will allow people to run sudo apt-get install instead, when we have a more isolated build system.

Please, if you have the time, consider opening an issue for this so we track it independently from the plantuml one.

[danwos]

Thanks for the fast answer. I have created an extra issue: #9599

[humitos]

In this other issue https://github.com/readthedocs/readthedocs.org/issues/9958#issuecomment-1406933680, there is an updated version about how to use PlantUML. It also uses a local version of PlantUML, so it can be the latest one if required.