Readme.rst 6.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217
  1. ================================================
  2. PlantUML plugin for Pelican rst and md documents
  3. ================================================
  4. This plugin allows you to define UML diagrams directly into rst or md documents using the great PlantUML_ tool.
  5. It gets the content of ``uml`` directive, passes it to the external program PlantUML_ and then links the generated image to the document.
  6. .. contents::
  7. Installation
  8. ============
  9. You need to install PlantUML_ (see the site for details) and Graphviz_ 2.26.3 or later. The plugin expects a program ``plantuml`` in the classpath. If not installed by your package manager, you can create a shell script and place it somewhere in the classpath. For example, save te following into ``/usr/local/bin/plantuml`` (supposing PlantUML_ installed into ``/opt/plantuml``):
  10. .. code-block:: bash
  11. #!/bin/bash
  12. java -jar /opt/plantuml/plantuml.jar ${@}
  13. For Gentoo_ there is an ebuild at http://gpo.zugaina.org/dev-util/plantuml/RDep: you can download the ebuild and the ``files`` subfolder or you can add the ``zugaina`` repository with _layman (reccomended).
  14. Usage
  15. =====
  16. Add ``plantuml`` to plugin list in ``pelicanconf.py``. For example:
  17. .. code-block:: ptyhon
  18. PLUGINS = [ "sitemap", "plantuml" ]
  19. One loaded the plugin register also the Pyhton-Markdown_ extension.
  20. RST usage
  21. ---------
  22. Use the ``uml`` directive to start UML diagram description. It is not necessary to enclose diagram body between ``@startuml`` and ``@enduml`` directives: they are added automatically before calling ``plantuml``.
  23. In addition to ``class`` and ``alt`` options common to all images, you can use the ``format`` option to select what kind of image must be produced. At the moment only ``png`` and ``svg`` are supported; the default is ``png``.
  24. Please note that the ``format`` option in not recognized by the ``plantuml`` extension of ``rst2pdf`` utility (call it with ``-e plantuml.py``) so if you use it you can get errors from that program.
  25. MD usage
  26. --------
  27. For use with the Pyhton-Markdown_ syntax, the UML block must be enclose with ``::uml::``:
  28. .. code-block:: markdown
  29. ::uml:: [format=...] [classes=...] [alt=...]
  30. PlantUML script
  31. ::end-uml::
  32. Please keep a blank line before ``::uml::`` and after ``::end-uml::`` to be sure that the UML code will be correctly recognized. See Examples_ for more details.
  33. With MD syntax options must be specified in the same line as the opening ``:uml::``, with the order ``format``, ``classes`` anmd ``alt``. The general syntax for option is
  34. .. code-block:: text
  35. option="value"
  36. Option can be enclosed with single or double quotes, as you like. Options defaults are the same as for the rst plugin.
  37. For pandoc_reader plugin users
  38. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  39. The plugin ``pandoc_reader`` sends the Markdown body to the pandoc_ tool which has it's own Markdown parser, written in Haskell_ language: Python_ plugins manipulating Markdown posts (such this) are not used because the entire body id passed to pandoc_ without any iteraction by Pelican_.
  40. For those who are using the ``pandoc_reader`` plugin and wants to include PlantUML_ diagrams, use the ``pandoc-plantuml`` script (only *nix, sorry): it is a wrapper for filtering the code blocks parsed by pandoc_ before
  41. writing out the converted file. It is an adaption of the great work by Kurt Bonne for his `pandoc-plantuml-filter <https://github.com/kbonne/pandoc-plantuml-filter.git>`_.
  42. To use it, copy the ``pandoc-plantuml`` file in a subdirectory of your pelican project (for example `pandoc_extensions`) and make sure it is executable (``chmod +x pandoc-plantuml``).
  43. In the ``pelicanconf.py`` configure the needed plugins:
  44. .. code-block:: python
  45. PLUGINS = ['pandoc_reader'] // Yes, plantuml plugin non necessary
  46. PANDOC_ARGS = ['--filter=pandoc_extensions/pandoc-plantuml']
  47. In Markdown posts use the following syntax to include PlantUML_ diagrams:
  48. .. code-block:: markdown
  49. ```plantuml
  50. @startuml
  51. Alice -> Bob: Authentication Request
  52. Bob --> Alice: Authentication Response
  53. Alice -> Bob: Another authentication Request
  54. Alice <-- Bob: another authentication Response
  55. @enduml
  56. ```
  57. Rendered images will bu put in the output/images folder.
  58. **NOTE:** ``pandoc-plantuml`` is broken from pandoc 1.16 cause an API change in pandoc ``Image`` function. I'm working on a fix but in the meanwhile use a version of pandoc prior to ``1.16`` .
  59. Debugging
  60. ---------
  61. The plugin can produce debugging informations to help to locate errors. To enable debugging execute ``pelican`` in debug mode:
  62. .. code-block:: console
  63. make DEBUG=1 html
  64. Examples
  65. ========
  66. Sequence diagram (from PlantUML_ site):
  67. .. code-block:: rst
  68. .. uml::
  69. :alt: Sample sequence diagram
  70. participant User
  71. User -> A: DoWork
  72. activate A #FFBBBB
  73. A -> A: Internal call
  74. activate A #DarkSalmon
  75. A -> B: << createRequest >>
  76. activate B
  77. B --> A: RequestCreated
  78. deactivate B
  79. deactivate A
  80. A -> User: Done
  81. deactivate A
  82. Output:
  83. .. image:: http://plantuml.sourceforge.net/imgp/sequence_022.png
  84. :alt: Sample sequence diagram
  85. Same diagram with Pyhton-Markdown_ syntax:
  86. .. code-block:: markdown
  87. ::uml:: format="png" alt="Sample sequence diagram"
  88. participant User
  89. User -> A: DoWork
  90. activate A #FFBBBB
  91. A -> A: Internal call
  92. activate A #DarkSalmon
  93. A -> B: << createRequest >>
  94. activate B
  95. B --> A: RequestCreated
  96. deactivate B
  97. deactivate A
  98. A -> User: Done
  99. deactivate A
  100. ::end-uml::
  101. Another example from PlantUML_ site (activity diagram):
  102. .. code-block:: rst
  103. .. uml::
  104. start
  105. :ClickServlet.handleRequest();
  106. :new page;
  107. if (Page.onSecurityCheck) then (true)
  108. :Page.onInit();
  109. if (isForward?) then (no)
  110. :Process controls;
  111. if (continue processing?) then (no)
  112. stop
  113. endif
  114. if (isPost?) then (yes)
  115. :Page.onPost();
  116. else (no)
  117. :Page.onGet();
  118. endif
  119. :Page.onRender();
  120. endif
  121. else (false)
  122. endif
  123. if (do redirect?) then (yes)
  124. :redirect process;
  125. else
  126. if (do forward?) then (yes)
  127. :Forward request;
  128. else (no)
  129. :Render page template;
  130. endif
  131. endif
  132. stop
  133. Generated image:
  134. .. image:: http://plantuml.sourceforge.net/imgp/activity2_009.png
  135. :alt: Sample activity diagram
  136. .. _PlantUML: http://plantuml.sourceforge.net
  137. .. _Sabayon: http://www.sabayon.org
  138. .. _Gentoo: http://www.gentoo.org
  139. .. _layman: http://wiki.gentoo.org/wiki/Layman
  140. .. _Graphviz: http://www.graphviz.org
  141. .. _Pyhton-Markdown: http://pythonhosted.org/Markdown
  142. .. _pandoc: http://johnmacfarlane.net/pandoc
  143. .. _Haskell: http://www.haskell.org/haskellwiki/Haskell
  144. .. _Python:: http://www.python.org
  145. .. _Pelican: http://docs.getpelican.com/en