Skip to content

PlantUML support for RST [Completed]

Jump to bottom
S.Lott edited this page Jul 18, 2022 · 1 revision

There are fundamental choices.

  1. Create something better than the existing uml-plantUml integration
  2. Use Sphinx, which offers it. Since this effort pre-dates sphinx, the idea of standing alone (relying only on docutils) is appealing. However, Sphinx seems like it might be a much cleaner approach, with lots and lots of options and styling.

See https://plantuml.com/docutils

The idea is to add a directive to wrap the PlantUML. This must be handled by a docutils extension. There arw two ways to package this:

This does not extend to other languages like LaTeX or HTML.

For HTML, see https://plantuml.com/jquery. The .w document would contain the necessary JQ add-on.

Fr LaTeX, see https://plantuml.com/latex. It's an addition to the tool chain, in effect. The .w document would incorporate the needed LaTeX add-ons.

Approach

Use Sphinx and the PlantUML add-on.

Discarded Approach

This is a separate project. New github repo, etc.

See https://docutils.sourceforge.io/docs/howto/rst-directives.html Specifically the implementation of the image node.

This can start as an application-specific directive, which means a special front-end command-line tool. See https://docutils.sourceforge.io/docs/howto/cmdline-tool.html. First, register the new option; then carry on normally.

Options

  -gui                To run the graphical user interface
  -tpng               To generate images using PNG format (default)
  -tsvg               To generate images using SVG format
  -teps               To generate images using EPS format
  -tpdf               To generate images using PDF format
  -tvdx               To generate images using VDX format
  -txmi               To generate XMI file for class diagram
  -tscxml             To generate SCXML file for state diagram
  -thtml              To generate HTML file for class diagram
  -ttxt               To generate images with ASCII art
  -tutxt              To generate images with ASCII art using Unicode characters
  -tlatex             To generate images using LaTeX/Tikz format
  -tlatex:nopreamble  To generate images using LaTeX/Tikz format without preamble
  -o[utput] "dir"     To generate images in the specified directory
  -DVAR1=value        To set a preprocessing variable as if '!define VAR1 value' were used
  -Sparam1=value      To set a skin parameter as if 'skinparam param1 value' were used
  -Ppragma1=value     To set pragma as if '!pragma pragma1 value' were used
  -I\path\to\file     To include file as if '!include file' were used
  -I\path\to\*.puml   To include files with pattern
  -theme xxx          To use a specific theme
  -charset xxx        To use a specific charset (default is windows-1251)
  -e[x]clude pattern  To exclude files that match the provided pattern
  -metadata           To retrieve PlantUML sources from PNG images
  -nometadata         To NOT export metadata in PNG/SVG generated files
  -checkmetadata              Skip PNG files that don't need to be regenerated
  -version            To display information about PlantUML and Java versions
  -v[erbose]          To have log information
  -quiet              To NOT print error message into the console
  -debugsvek          To generate intermediate svek files
  -h[elp]             To display this help message
  -testdot            To test the installation of graphviz
  -graphvizdot "exe"  To specify dot executable
  -p[ipe]             To use stdin for PlantUML source and stdout for PNG/SVG/EPS generation
  -encodesprite 4|8|16[z] "file"      To encode a sprite at gray level (z for compression) from an image
  -computeurl|-encodeurl      To compute the encoded URL of a PlantUML source file
  -decodeurl          To retrieve the PlantUML source from an encoded URL
  -syntax             To report any syntax error from standard input without generating images
  -language           To print the list of PlantUML keywords
  -checkonly          To check the syntax of files without generating images
  -failfast           To stop processing as soon as a syntax error in diagram occurs
  -failfast2          To do a first syntax check before processing files, to fail even faster
  -noerror            To skip images when error in diagrams
  -duration           To print the duration of complete diagrams processing
  -nbthread N         To use (N) threads for processing
  -nbthread auto      To use 4 threads for processing
  -timeout N          Processing timeout in (N) seconds. Defaults to 15 minutes (900 seconds).
  -author[s]          To print information about PlantUML authors
  -overwrite          To allow to overwrite read only files
  -printfonts         To print fonts available on your system
  -enablestats        To enable statistics computation
  -disablestats       To disable statistics computation (default)
  -htmlstats          To output general statistics in file plantuml-stats.html
  -xmlstats           To output general statistics in file plantuml-stats.xml
  -realtimestats      To generate statistics on the fly rather than at the end
  -loopstats          To continuously print statistics about usage
  -splash             To display a splash screen with some progress bar
  -progress           To display a textual progress bar in console
  -pipeimageindex N   To generate the Nth image with pipe option
  -stdlib             To print standard library info
  -extractstdlib      To extract PlantUML Standard Library into stdlib folder
  -filedir xxx        To behave as if the PlantUML source is in this dir (only affects '-pipe' and PicoWeb 'POST /render')
  -filename "example.puml"    To override %filename% variable
  -preproc            To output preprocessor text of diagrams
  -cypher             To cypher texts of diagrams so that you can share them
  -picoweb            To start internal HTTP Server. See https://plantuml.com/picoweb

Of these, some are not useful. -gui, -picoweb, -filedir, -h, -testdot are for an interactive user, as are -syntax, -language, and -checkonly, -author, -splash. The -I... and -e[x], -pipeimageindex, similarly, aren't appropriate from inside RST.

Processing

The Docutils directive defines the options from the parsed node. It will also gather the PlantUML source.

When "run":

  • Write a temporary file.
  • Run the Java image to convert, creating either a temporary file or the expected named file.
  • Build the image node.
Clone this wiki locally