sandbox/uml-plantUml/usage/README.txt

   1 INFO: Generate UML diagrams from docutils using PlantUML
   2 ========================================================
   3
   4 Being able to generate html/pdf documents with diagrams from vi or automaticaly is great for me. Many many thanks to docutils and plantuml developers for sharing their vision and the effort!
   5
   6 ASK: mauriciocap@gmail.com / http://www.mauriciocap.com.ar
   7
   8 SEE: http://plantuml.sourceforge.net/ Generate UML diagrams from text, runnable from a single jar!
   9
  10 SEE: http://docutils.sourceforge.net/ Conveniently write and generate documents in various output formats
  11
  12 SEE: http://code.google.com/p/rst2pdf/ Generate PDF output without latex in windows
  13
  14 Install:
  15 --------
  16 **WARNING:** the directive EXECUTES an external program with an argument passed from the rst input file! Don't use it if to process input files you don't trust.
  17
  18 #. replace/patch your docutils distribution with the files in src/, e.g. in my cygwin instance
  19
  20 ::
  21         # cp -r src/* /usr/lib/python2.5/site-packages/docutils
  22
  23 #. see usage examples in usage/ including how to setup defaults PlantUML
  24
  25 Examples:
  26 ---------
  27
  28 SEE: diagrams at http://plantuml.sourceforge.net/ , ALL should work as long as your plantuml installation works
  29
  30 USE the "uml" directive and write an indented block of PlantUML commands. No arguments are required, an image will be generated and inlined. The name is derived from the input line number, the generatd plantuml "source" is keep in the same directory.
  31
  32 .. uml::
  33
  34         actor User
  35         participant "First Class" as A
  36         participant "Second Class" as B
  37         participant "Last Class" as C
  38
  39         User -> A: DoWork
  40         activate A
  41
  42         A -> B: << createRequest >>
  43         activate B
  44
  45         B -> C: DoWork
  46         activate C
  47         C --> B: WorkDone
  48         destroy C
  49
  50         B --> A: Request <u>Created</u>
  51         deactivate B
  52
  53         A --> User: Done
  54         deactivate A
  55
  56 The same here:
  57
  58 .. uml::
  59
  60         actor User
  61         participant "First Class" as A
  62         participant "Second Class" as B
  63         participant "Last Class" as C
  64
  65         User -> A: DoWork
  66         activate A
  67
  68 You can pass a filename for the image (WITHOUT extension) as an optional parameter.
  69
  70 .. uml:: uml2/myDiagram123
  71
  72         actor User
  73         participant "First Class" as A
  74         participant "Second Class" as B
  75         participant "Last Class" as C
  76
  77         User -> A: DoMoreWork
  78         activate A
  79
  80 Development:
  81 ------------
  82
  83 This was a quick (but effective) hack :) In the near future I'd like to:
  84
  85 * implement the image generation as a "writer" instead, as docutils architecture suggest
  86
  87 * contribute tests and better documentation
  88
  89 Please let me know how can I be of more help!
  90
  91 mauriciocap@gmail.com / http://www.mauriciocap.com.ar