sandbox/uml-plantUml/usage/README.html

   1 <?xml version="1.0" encoding="utf-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <meta name="generator" content="Docutils 0.7: http://docutils.sourceforge.net/" />
   7 <title>INFO: Generate UML diagrams from docutils using PlantUML</title>
   8 <style type="text/css">
   9
  10 /*
  11 :Author: David Goodger (goodger@python.org)
  12 :Id: $Id$
  13 :Copyright: This stylesheet has been placed in the public domain.
  14
  15 Default cascading style sheet for the HTML output of Docutils.
  16
  17 See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
  18 customize this style sheet.
  19 */
  20
  21 /* used to remove borders from tables and images */
  22 .borderless, table.borderless td, table.borderless th {
  23   border: 0 }
  24
  25 table.borderless td, table.borderless th {
  26   /* Override padding for "table.docutils td" with "! important".
  27      The right padding separates the table cells. */
  28   padding: 0 0.5em 0 0 ! important }
  29
  30 .first {
  31   /* Override more specific margin styles with "! important". */
  32   margin-top: 0 ! important }
  33
  34 .last, .with-subtitle {
  35   margin-bottom: 0 ! important }
  36
  37 .hidden {
  38   display: none }
  39
  40 a.toc-backref {
  41   text-decoration: none ;
  42   color: black }
  43
  44 blockquote.epigraph {
  45   margin: 2em 5em ; }
  46
  47 dl.docutils dd {
  48   margin-bottom: 0.5em }
  49
  50 /* Uncomment (and remove this text!) to get bold-faced definition list terms
  51 dl.docutils dt {
  52   font-weight: bold }
  53 */
  54
  55 div.abstract {
  56   margin: 2em 5em }
  57
  58 div.abstract p.topic-title {
  59   font-weight: bold ;
  60   text-align: center }
  61
  62 div.admonition, div.attention, div.caution, div.danger, div.error,
  63 div.hint, div.important, div.note, div.tip, div.warning {
  64   margin: 2em ;
  65   border: medium outset ;
  66   padding: 1em }
  67
  68 div.admonition p.admonition-title, div.hint p.admonition-title,
  69 div.important p.admonition-title, div.note p.admonition-title,
  70 div.tip p.admonition-title {
  71   font-weight: bold ;
  72   font-family: sans-serif }
  73
  74 div.attention p.admonition-title, div.caution p.admonition-title,
  75 div.danger p.admonition-title, div.error p.admonition-title,
  76 div.warning p.admonition-title {
  77   color: red ;
  78   font-weight: bold ;
  79   font-family: sans-serif }
  80
  81 /* Uncomment (and remove this text!) to get reduced vertical space in
  82    compound paragraphs.
  83 div.compound .compound-first, div.compound .compound-middle {
  84   margin-bottom: 0.5em }
  85
  86 div.compound .compound-last, div.compound .compound-middle {
  87   margin-top: 0.5em }
  88 */
  89
  90 div.dedication {
  91   margin: 2em 5em ;
  92   text-align: center ;
  93   font-style: italic }
  94
  95 div.dedication p.topic-title {
  96   font-weight: bold ;
  97   font-style: normal }
  98
  99 div.figure {
 100   margin-left: 2em ;
 101   margin-right: 2em }
 102
 103 div.footer, div.header {
 104   clear: both;
 105   font-size: smaller }
 106
 107 div.line-block {
 108   display: block ;
 109   margin-top: 1em ;
 110   margin-bottom: 1em }
 111
 112 div.line-block div.line-block {
 113   margin-top: 0 ;
 114   margin-bottom: 0 ;
 115   margin-left: 1.5em }
 116
 117 div.sidebar {
 118   margin: 0 0 0.5em 1em ;
 119   border: medium outset ;
 120   padding: 1em ;
 121   background-color: #ffffee ;
 122   width: 40% ;
 123   float: right ;
 124   clear: right }
 125
 126 div.sidebar p.rubric {
 127   font-family: sans-serif ;
 128   font-size: medium }
 129
 130 div.system-messages {
 131   margin: 5em }
 132
 133 div.system-messages h1 {
 134   color: red }
 135
 136 div.system-message {
 137   border: medium outset ;
 138   padding: 1em }
 139
 140 div.system-message p.system-message-title {
 141   color: red ;
 142   font-weight: bold }
 143
 144 div.topic {
 145   margin: 2em }
 146
 147 h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
 148 h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
 149   margin-top: 0.4em }
 150
 151 h1.title {
 152   text-align: center }
 153
 154 h2.subtitle {
 155   text-align: center }
 156
 157 hr.docutils {
 158   width: 75% }
 159
 160 img.align-left, .figure.align-left, object.align-left {
 161   clear: left ;
 162   float: left ;
 163   margin-right: 1em }
 164
 165 img.align-right, .figure.align-right, object.align-right {
 166   clear: right ;
 167   float: right ;
 168   margin-left: 1em }
 169
 170 img.align-center, .figure.align-center, object.align-center {
 171   display: block;
 172   margin-left: auto;
 173   margin-right: auto;
 174 }
 175
 176 .align-left {
 177   text-align: left }
 178
 179 .align-center {
 180   clear: both ;
 181   text-align: center }
 182
 183 .align-right {
 184   text-align: right }
 185
 186 /* reset inner alignment in figures */
 187 div.align-right {
 188   text-align: left }
 189
 190 /* div.align-center * { */
 191 /*   text-align: left } */
 192
 193 ol.simple, ul.simple {
 194   margin-bottom: 1em }
 195
 196 ol.arabic {
 197   list-style: decimal }
 198
 199 ol.loweralpha {
 200   list-style: lower-alpha }
 201
 202 ol.upperalpha {
 203   list-style: upper-alpha }
 204
 205 ol.lowerroman {
 206   list-style: lower-roman }
 207
 208 ol.upperroman {
 209   list-style: upper-roman }
 210
 211 p.attribution {
 212   text-align: right ;
 213   margin-left: 50% }
 214
 215 p.caption {
 216   font-style: italic }
 217
 218 p.credits {
 219   font-style: italic ;
 220   font-size: smaller }
 221
 222 p.label {
 223   white-space: nowrap }
 224
 225 p.rubric {
 226   font-weight: bold ;
 227   font-size: larger ;
 228   color: maroon ;
 229   text-align: center }
 230
 231 p.sidebar-title {
 232   font-family: sans-serif ;
 233   font-weight: bold ;
 234   font-size: larger }
 235
 236 p.sidebar-subtitle {
 237   font-family: sans-serif ;
 238   font-weight: bold }
 239
 240 p.topic-title {
 241   font-weight: bold }
 242
 243 pre.address {
 244   margin-bottom: 0 ;
 245   margin-top: 0 ;
 246   font: inherit }
 247
 248 pre.literal-block, pre.doctest-block {
 249   margin-left: 2em ;
 250   margin-right: 2em }
 251
 252 span.classifier {
 253   font-family: sans-serif ;
 254   font-style: oblique }
 255
 256 span.classifier-delimiter {
 257   font-family: sans-serif ;
 258   font-weight: bold }
 259
 260 span.interpreted {
 261   font-family: sans-serif }
 262
 263 span.option {
 264   white-space: nowrap }
 265
 266 span.pre {
 267   white-space: pre }
 268
 269 span.problematic {
 270   color: red }
 271
 272 span.section-subtitle {
 273   /* font-size relative to parent (h1..h6 element) */
 274   font-size: 80% }
 275
 276 table.citation {
 277   border-left: solid 1px gray;
 278   margin-left: 1px }
 279
 280 table.docinfo {
 281   margin: 2em 4em }
 282
 283 table.docutils {
 284   margin-top: 0.5em ;
 285   margin-bottom: 0.5em }
 286
 287 table.footnote {
 288   border-left: solid 1px black;
 289   margin-left: 1px }
 290
 291 table.docutils td, table.docutils th,
 292 table.docinfo td, table.docinfo th {
 293   padding-left: 0.5em ;
 294   padding-right: 0.5em ;
 295   vertical-align: top }
 296
 297 table.docutils th.field-name, table.docinfo th.docinfo-name {
 298   font-weight: bold ;
 299   text-align: left ;
 300   white-space: nowrap ;
 301   padding-left: 0 }
 302
 303 h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
 304 h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
 305   font-size: 100% }
 306
 307 ul.auto-toc {
 308   list-style-type: none }
 309
 310 </style>
 311 </head>
 312 <body>
 313 <div class="document" id="info-generate-uml-diagrams-from-docutils-using-plantuml">
 314 <h1 class="title">INFO: Generate UML diagrams from docutils using PlantUML</h1>
 315
 316 <p>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!</p>
 317 <p>ASK: <a class="reference external" href="mailto:mauriciocap&#64;gmail.com">mauriciocap&#64;gmail.com</a> / <a class="reference external" href="http://www.mauriciocap.com.ar">http://www.mauriciocap.com.ar</a></p>
 318 <p>SEE: <a class="reference external" href="http://plantuml.sourceforge.net/">http://plantuml.sourceforge.net/</a> Generate UML diagrams from text, runnable from a single jar!</p>
 319 <p>SEE: <a class="reference external" href="http://docutils.sourceforge.net/">http://docutils.sourceforge.net/</a> Conveniently write and generate documents in various output formats</p>
 320 <p>SEE: <a class="reference external" href="http://code.google.com/p/rst2pdf/">http://code.google.com/p/rst2pdf/</a> Generate PDF output without latex in windows</p>
 321 <div class="section" id="install">
 322 <h1>Install:</h1>
 323 <p><strong>WARNING:</strong> 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.</p>
 324 <ol class="arabic simple">
 325 <li>replace/patch your docutils distribution with the files in src/, e.g. in my cygwin instance</li>
 326 </ol>
 327 <dl class="docutils">
 328 <dt>::</dt>
 329 <dd># cp -r src/* /usr/lib/python2.5/site-packages/docutils</dd>
 330 </dl>
 331 <ol class="arabic simple">
 332 <li>see usage examples in usage/ including how to setup defaults PlantUML</li>
 333 </ol>
 334 </div>
 335 <div class="section" id="examples">
 336 <h1>Examples:</h1>
 337 <p>SEE: diagrams at <a class="reference external" href="http://plantuml.sourceforge.net/">http://plantuml.sourceforge.net/</a> , ALL should work as long as your plantuml installation works</p>
 338 <p>USE the &quot;uml&quot; 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 &quot;source&quot; is keep in the same directory.</p>
 339 <img alt="uml/000032.png" src="uml/000032.png" />
 340 <p>The same here:</p>
 341 <img alt="uml/000058.png" src="uml/000058.png" />
 342 <p>You can pass a filename for the image (WITHOUT extension) as an optional parameter.</p>
 343 <img alt="uml2/myDiagram123.png" src="uml2/myDiagram123.png" />
 344 </div>
 345 <div class="section" id="development">
 346 <h1>Development:</h1>
 347 <p>This was a quick (but effective) hack :) In the near future I'd like to:</p>
 348 <ul class="simple">
 349 <li>implement the image generation as a &quot;writer&quot; instead, as docutils architecture suggest</li>
 350 <li>contribute tests and better documentation</li>
 351 </ul>
 352 <p>Please let me know how can I be of more help!</p>
 353 <p><a class="reference external" href="mailto:mauriciocap&#64;gmail.com">mauriciocap&#64;gmail.com</a> / <a class="reference external" href="http://www.mauriciocap.com.ar">http://www.mauriciocap.com.ar</a></p>
 354 </div>
 355 </div>
 356 </body>
 357 </html>