.. -*- coding: utf-8 -*- .. role:: sref(numref) .. role:: xref(numref) .. Copyright (C) 2018, Wolfgang Scherer, .. .. This file is part of Documentation Standard. .. .. Permission is granted to copy, distribute and/or modify this document .. under the terms of the GNU Free Documentation License, Version 1.3 .. or any later version published by the Free Software Foundation; .. with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. .. A copy of the license is included in the section entitled "GNU .. Free Documentation License". .. inline comments (with du_comment_role) .. role:: rem(comment) .. role:: html(raw) :format: html .. role:: shx(code) :language: sh .. rst-class:: xnarrow xmedium large xhuge xultra .. _`sec:Unified Modeling Language`: ############################################# :rem:`|||:sec:|||`\ Unified Modeling Language ############################################# .. >>CODD See `the components of a doctoral dissertation and their order `_ .. >>CODD Dedication .. >>CODD Epigraph .. >>CODD Abstract .. compound:: .. \|:here:| .. >>CODD Introduction ================================================== :rem:`|||:sec:|||`\ UML Introduction ================================================== `UML`_ (Unified Modeling Language) is an ISO standardized method for describing programs. Its resulting diagrams are widely taught and should therefore be used as much as possible. The standard is mostly about the inner mechanism of the modeling language and not so much about the diagrams, however, the diagrams are the most useful part, as they are quickly understood even by non-programmers. ------------------------------------------------- :rem:`|:sec:|`\ Getting Started with UML Diagrams ------------------------------------------------- Check out these web-sites - | `Unified Modeling Language (UML) description`_ | The most comprehensive reference for UML 2.5 diagrams - | `Sparx Systems - UML 2 Tutorial`_ | A conscise overview of UML 2 diagrams This is the inheritance hierarchy of `UML diagrams`_ supported by `PlantUML`_ (clickable in HTML): .. uml:: _static/uml-diagram-hierarchy.puml .. _`Unified Modeling Language (UML) description`: https://www.uml-diagrams.org/ .. _`Sparx Systems - UML 2 Tutorial`: http://www.sparxsystems.com/resources/uml2_tutorial/index.html - `UML 2.5 Diagram`_ - `Structure Diagram`_ - `Class Diagram`_ - `Object Diagram`_ - `Component Diagram`_ - `Deployment Diagram`_ - `Behavior Diagram`_ - `Use Case Diagram`_ - `Activity Diagram`_ - `State Machine Diagram`_ - `Interaction Diagram`_ - `Message Sequence Diagram`_ - `Timing Diagram`_ -------------------------------------------------- :rem:`|:sec:|`\ Quick Reference Guides -------------------------------------------------- - :download:`Local copy of <_static/UML-2-5-Referenz-Karte-doppelseitig.pdf>` from `UML 2.5 Referenz - Karte, Diagramm, Notation`_ - :download:`Local copy of <_static/UML-Quick-Reference-Guide-PDQM.pdf>` `PDQM UML Quick Reference Guide`_ - `Allen Holub's UML Quick Reference`_ - :download:`Local copy of <_static/no-magic-quick-reference-guide_uml.pdf>` `UML Quick Reference Guide`_ from `No Magic`_. - :download:`Local copy of <_static/lou-franco-cheatsheet.pdf>` `UML Cheatsheet`_ from `Lou Franco: code, apps, and writings`_ .. _`UML 2.5 Referenz - Karte, Diagramm, Notation`: https://www.oio.de/public/objektorientierung/uml-referenz-2-5/ .. _`UML 2.1 Referenz - Karte, Diagramm, Notation`: https://www.oio.de/public/objektorientierung/uml-referenz-2-1/ .. _`PDQM UML Quick Reference Guide`: http://ww.pdqm.cz/Standards/Analysis/UML-Quick-Reference-Guide.pdf .. _`Allen Holub's UML Quick Reference`: https://holub.com/uml/ .. _UML Quick Reference Guide: https://www.nomagic.com/component/phocadownload/category/1-quick-reference-guides?download=2:uml-quick-reference-guide .. _`No Magic`: https://www.nomagic.com/products/magicdraw .. _`UML Cheatsheet`: http://loufranco.com/blog/assets/cheatsheet.pdf .. _`Lou Franco: code, apps, and writings`: http://loufranco.com/ -------------------------------------------------- :rem:`|:sec:|`\ Reference Guides and Tutorials -------------------------------------------------- - `Practical UML: A Hands-On Introduction for Developers`_ - `Microsoft - Create models for your app`_ - `tutorialspoint - UML Tutorial`_ (old) .. _`Practical UML: A Hands-On Introduction for Developers`: http://edn.embarcadero.com/article/31863 .. _`Microsoft - Create models for your app`: https://msdn.microsoft.com/en-us/library/dd409436.aspx .. _`tutorialspoint - UML Tutorial`: https://www.tutorialspoint.com/uml/index.htm -------------------------------------------------- :rem:`|:sec:|`\ UML Tools -------------------------------------------------- The site `UML tools : Curated selection of free, online, OSS, for MAC,... tools`_ is an extensive collection of UML tool information. .. _`UML tools : Curated selection of free, online, OSS, for MAC,... tools`: https://modeling-languages.com/uml-tools/ .. _uml gui tools: ---------------------------------------------------- :rem:`||:sec:||`\ UML GUI Tools ---------------------------------------------------- Many `UML`_ tools specialize in providing a GUI environment to design diagrams with extensive support for a detailed standards-compliant specification of elements. The output is standardized but unreadable `XMI`_ (XML Metadata Interchange). This disqualifies most of the `UML`_ GUI tools for proper adhoc ASCII level documentation. Creating unreadable diagram defintions, which require HTML/PDF/image generation before they become useful is highly undesirable if your focus is on programming. The incentive for a programmer to keep the documentation up to date is negative\ [#]_. GUI Tools are still useful to explore the graphical notation of the various diagrams. See ref:`gui tools with uml standard support`. --------------------------------------------------------------------- :rem:`||:sec:||`\ Tools for Translating Declarative Specs to Diagrams --------------------------------------------------------------------- If your focus is on modeling, the :ref:`uml gui tools` are a better choice, but if your main task is programming, this is the way to go. The `introduction to UMLGraph `_ provides an excellent argument for declarative specification of UML diagrams. The `Stack Overflow`_ question "`Generating UML diagrams from textual representation`_" references a list of tools (`Text to UML tools`_), but highlights `PlantUML`_. The `PlantUML`_ tool's definition language is quite readable without the rendered diagrams. It also integrates with many tools (namely :command:`Emacs` and `Sphinx`_)- (See section :ref:`plantuml tool`). The GitHubGist `generate PlantUML definition from python sources`_ provides :command:`genclass.py`, locally renamed to :command:`gen_plantuml.py`. This command helps with the initial UML class diagrams and further updates. See section :ref:`auto generators` for an example generator of a class diagram for global variables/functions. `yUML`_ has sphinx integration, but is very limited in regarding readability and choice of diagrams (see section :ref:`yuml tool`). `Umple: Merging Modeling with Programming`_, i.e. it works as a programming language pre-processor (programming language extension, roundtrip). .. >>CODD Chapter ================================================== :rem:`|||:sec:|||`\ UML Diagrams ================================================== The most important UML Diagrams are - `Use Case Diagram`_ - `Class Diagram`_ - `Activity Diagram`_ - `State Machine Diagram`_ - `Sequence Diagram`_ -------------------------------------------------- :rem:`||:sec:||`\ Use Case Diagram -------------------------------------------------- Use case diagrams are usually referred to as behavior diagrams used to describe a set of actions (use cases) that some system or systems (subject) should or can perform in collaboration with one or more external users of the system (actors). Each use case should provide some observable and valuable result to the actors or other stakeholders of the system. (https://www.uml-diagrams.org/use-case-diagrams.html) Here is the use case diagram of a workers day:: .. uml:: @startuml worker1 -> (work) worker2 -> (work) worker1 -> (home1) worker2 -> (home2) @enduml This is how it is rendered in Sphinx: .. uml:: @startuml worker1 -> (work) worker2 -> (work) worker1 -> (home1) worker2 -> (home2) @enduml For details see `PlantUML Language Reference Guide`_. -------------------------------------------------- :rem:`||:sec:||`\ Class Diagram -------------------------------------------------- Class diagram is UML structure diagram which shows structure of the designed system at the level of classes and interfaces, shows their features, constraints and relationships - associations, generalizations, dependencies, etc. (https://www.uml-diagrams.org/class-diagrams-overview.html) `PlantUML`_ example (`PlantUML Language Reference Guide`_):: .. uml:: @startuml class OneClass { -private : string +public : int -priv_method() +pub_method() } ' stereotype class TwoClass << (I, #ffcccc) interface >> OneClass ..|> TwoClass hide TwoClass members @enduml This is how it is rendered in Sphinx: .. uml:: @startuml class OneClass { -private : string +public : int -priv_method() +pub_method() } ' stereotype class TwoClass << (I, #ffcccc) interface >> OneClass ..|> TwoClass hide TwoClass members @enduml ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :rem:`|:sec:|`\ Associations between classes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ UML association is relationship between classifiers to show that instances of classifiers could be either linked to each other or combined into some aggregation. See `the definitive Guide to UML associations`_. :Association: is a relationship where all objects have their own lifecycle and there is no owner. Let's take an example of Teacher and Student. Multiple students can associate with single teacher and single student can associate with multiple teachers, but there is no ownership between the objects and both have their own lifecycle. Both can be created and deleted independently. :Aggregation: is a specialised form of Association where all objects have their own lifecycle, but there is ownership and child objects can not belong to another parent object. Let's take an example of Department and teacher. A single teacher can not belong to multiple departments, but if we delete the department, the teacher object will not be destroyed. We can think about it as a “has-a” relationship. :Composition: is again specialised form of Aggregation and we can call this as a “death” relationship. It is a strong type of Aggregation. Child object does not have its lifecycle and if parent object is deleted, all child objects will also be deleted. Let's take again an example of relationship between House and Rooms. House can contain multiple rooms - there is no independent life of room and any room can not belong to two different houses. If we delete the house - room will automatically be deleted. Let's take another example relationship between Questions and Options. Single questions can have multiple options and option can not belong to multiple questions. If we delete the questions, options will automatically be deleted. Source: `StackExchange `_ `PlantUML`_ offers various association types: +--------------------------+----------+-------------------------+ | Relation | Symbol | Description | +==========================+==========+=========================+ | Association | ``--`` | no owner, navigability | | | | unspecified | +--------------------------+----------+-------------------------+ | Directed Association | ``<--`` | no owner, navigable | +--------------------------+----------+-------------------------+ | Association | ``x--`` | no owner, not navigable | +--------------------------+----------+-------------------------+ | Aggregation | ``o--`` | owner, but independent | +--------------------------+----------+-------------------------+ | Composition | ``*--`` | owner and dependent | +--------------------------+----------+-------------------------+ | Dependency | ``<..`` | no owner | +--------------------------+----------+-------------------------+ | Generalization/Extension | ``<│--`` | | +--------------------------+----------+-------------------------+ | Realization | ``<│..`` | | +--------------------------+----------+-------------------------+ | Nesting | ``+--`` | | +--------------------------+----------+-------------------------+ It is possible to replace ``--`` by ``..`` for broken lines. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :rem:`|:sec:|`\ Class Diagram Examples ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Naming conventions, visibility and types in global namespace and within classes: .. uml:: @startuml class "global" as G0 << (G, #ffcccc) >> { VARIABLE_NAME ClassName function_name() } note bottom: Naming conventions\nin global namespace class "Class" as C0 { {field} field_name_1 {field} field_name_2 {method} method_name_1() {method} method_name_2() } note right: Naming conventions\nin class class "ClassWithStuff" as C1 { -_private +attrib +list[] +dict{} } C1 : -_private_method() C1 : +method() note right: Visibility and type G0 -right[hidden]- C0 C0 -down[hidden]- C1 @enduml Enums can be used to describe variable collections: .. uml:: @startuml enum SOME_STUFF_ { SOME_STUFF_HERE SOME_STUFF_THERE SOME_STUFF_ANY SOME_STUFF_WHERE } hide SOME_STUFF_ methods @enduml Here is a more elaborate class diagram in :file:`_static/big-brother.puml`: .. literalinclude:: _static/big-brother.puml It can be included with the `uml` directive:: .. uml:: _static/big-brother.puml :caption: Big Brother is watching you .. uml:: _static/big-brother.puml :caption: Big Brother is watching you or specify path to external `PlantUML`_ file: .. uml:: _static/external.puml You can specify height, width, scale and align: .. uml:: :scale: 50 % :align: center Foo <|-- Bar You can specify a caption: .. uml:: :caption: Caption with **bold** and *italic* :width: 50mm Foo <|-- Bar |:todo:| describe `uml` directive explicitely If the `uml` directive has a caption (via option :caption:), it behaves like the `figure` directive. Otherwise, it behaves like the `image` directive. -------------------------------------------------- :rem:`||:sec:||`\ Activity Diagram -------------------------------------------------- Activity diagram is UML behavior diagram which shows flow of control or object flow with emphasis on the sequence and conditions of the flow. The actions coordinated by activity models can be initiated because other actions finish executing, because objects and data become available, or because some events external to the flow occur. (https://www.uml-diagrams.org/activity-diagrams.html) .. note:: It is **not** a **data flow diagram!** See `State Machine Diagram vs Activity Diagram`_ for a basic explanation of the differences. .. _`State Machine Diagram vs Activity Diagram`: https://www.visual-paradigm.com/guide/uml-unified-modeling-language/state-machine-diagram-vs-activity-diagram/ Here is the activity diagram of a persons daily routine:: .. uml:: @startuml !include _static/call-bevahor.puml start :alarm clock rings; :turn off the alarm clock; if(is it weekend?) then (yes) :go back to sleep; else (no) :eat; :wash; :CALL(go to work); endif stop @enduml This is how it is rendered in Sphinx: .. uml:: @startuml !include _static/call-behavior.puml start :alarm clock rings; :turn of the alarm clock; if(is it weekend?) then (yes) :go back to sleep; else (no) :eat; :wash; :CALL(go to work); endif stop @enduml For details see `PlantUML Language Reference Guide`_. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :rem:`|:sec:|`\ Activity Diagram Examples ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Here is the activity diagram to check a person `BB.check(person)`: .. uml:: start :assume person is boring; while (person is boring\n**and** time is not up) is (yes) if (person acts strange) then (yes) :person is now suspicious; else (no) endif endwhile (no) if (is person suspicious?) then (yes) :BB.suspect(person); else (no) :BB.vindicate(person); endif stop Another activity Diagram: .. uml:: :caption: Activitiy of the day @startuml start if (Graphviz installed ?) then (yes) :process all\ndiagrams <$ws>; else (no) :process only __sequence__ and __activity__ diagrams; endif stop @enduml -------------------------------------------------- :rem:`||:sec:||`\ State Machine Diagram -------------------------------------------------- State machine diagram is a behavior diagram which shows discrete behavior of a part of designed system through finite state transitions. State machine diagrams can also be used to express the usage protocol of part of a system. (https://www.uml-diagrams.org/state-machine-diagrams.html) Here is the State Machine Diagram of the procedure of starting a software project:: .. uml:: @startuml state plan as "Planning Project" plan : identify necessary UML diagram state create as "Create UML Diagram" state draw as "Draw UML Diagram" draw : modify diagram state bless as "Blessing" bless : discuss UML Diagram with boss state coding as "Programming" state doc as "Document" [*] --> plan plan --> bless : finished create --> draw draw --> bless bless --> plan : missing diagram bless --> plan : superfluous diagram bless --> create : new diagram\nblessed bless --> draw : error in\ndiagram bless --> coding : all diagrams\nfinished coding --> doc : new object doc --> coding : finished doc --> plan : missing diagram coding --> [*] @enduml This is how it is rendered in Sphinx: .. uml:: @startuml state plan as "Planning Project" plan : identify necessary UML diagram state create as "Create UML Diagram" state draw as "Draw UML Diagram" draw : modify diagram state bless as "Blessing" bless : discuss UML Diagram with boss state coding as "Programming" state doc as "Document" [*] --> plan plan --> bless : finished create --> draw draw --> bless bless --> plan : missing diagram bless --> plan : superfluous diagram bless --> create : new diagram\nblessed bless --> draw : error in\ndiagram bless --> coding : all diagrams\nfinished coding --> doc : new object doc --> coding : finished doc --> plan : missing diagram coding --> [*] @enduml See `Choice Pseudostate and Guard Condition in State Diagrams`_ for additional state diagram syntax:: @startuml left to right direction state choice <> state alt state fork <> state p1 state p2 state join <> state end <> [*] --> choice choice --> alt alt --> fork choice --> fork fork --> p1 fork --> p2 p1 --> join p2 --> join join --> end @enduml rendered as: .. uml:: @startuml left to right direction state choice <> state alt state fork <> state p1 state p2 state join <> state end <> [*] --> choice choice --> alt alt --> fork choice --> fork fork --> p1 fork --> p2 p1 --> join p2 --> join join --> end @enduml .. _`Choice Pseudostate and Guard Condition in State Diagrams`: http://forum.plantuml.net/?qa=1159/choice-pseudostate-and-guard-condition-in-state-diagrams .. _plantuml tool: -------------------------------------------------- :rem:`||:sec:||`\ Sequence Diagram -------------------------------------------------- `Sequence diagram`_ is the most common kind of `interaction diagram`_, which focuses on the message interchange between a number of lifelines. `Sequence diagram`_ describes an interaction by focusing on the sequence of messages that are exchanged, along with their corresponding occurrence specifications on the lifelines. (https://www.uml-diagrams.org/sequence-diagrams.html) Here is the sequence diagram of a short conversation between me and my boss:: .. uml:: Dominik -> Wolfgang : Am I doing\nit correctly? Wolfgang -> Dominik : Nice try\ndo it again! This is how it is rendered in Sphinx: .. uml:: Dominik -> Wolfgang: Am I doing\nit correctly? Wolfgang -> Dominik: Nice try\ndo it again! For details see `PlantUML Language Reference Guide`_. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :rem:`|:sec:|`\ Sequence Diagram Examples ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. uml:: Alice -> Bob: Hi! Alice <- Bob: How are you? ================================================== :rem:`|||:sec:|||`\ PlantUML ================================================== `PlantUML`_ is (in its own words) an open-source tool that uses simple textual descriptions to draw UML diagrams. See also sections :ref:`plantuml installation` and :ref:`plantuml emacs mode` below. -------------------------------------------------- :rem:`||:sec:||`\ PlantUML Usage -------------------------------------------------- The :download:`PlantUML Language Reference Guide <_static/PlantUML_Language_Reference_Guide.pdf>` is available locally and describes the standard `PlantUML`_ diagrams. However, some diagrams are only explained at the `PlantUML`_ web site. Since `PlantUML`_ is the standard documentation tool for UML diagrams, specifying diagrams is explained, where the UML diagrams are described. Here are just some experiments with special diagram types. Salt is meant for GUI specifications: .. uml:: @startuml salt {# Just plain text | { () Unchecked radio | [] Unchecked box (X) Checked radio | [X] Checked box } . | "Enter text here" [This is my button] | ^This is a droplist^ } 'The only difference between actor 'and participant is the drawing @enduml .. _`PlantUML Language Reference Guide`: _static/PlantUML_Language_Reference_Guide.pdf .. _plantuml installation: -------------------------------------------------- :rem:`||:sec:||`\ PlantUML Installation -------------------------------------------------- `PlantUML`_ is available as a ubuntu package: .. code-block:: sh apt-get install plantuml Besides `numerous other integrations `_ there is also a |sphinx extension module|_ available: .. code-block:: sh apt-get install python-sphinxcontrib.plantuml apt-get install python3-sphinxcontrib.plantuml The standard ubuntu packages are too old (sphinx: 0.5)! Use the backported versions (sphinx: 0.11) which are available in the `local repository `_: .. code-block:: sources.list deb [trusted=yes] http://scherer.wiedenmann.intern/repository xenial main deb-src [trusted=yes] http://scherer.wiedenmann.intern/repository xenial main .. |sphinx extension module| replace:: :command:`sphinx` extension module .. _`sphinx extension module`: https://pypi.python.org/pypi/sphinxcontrib-plantuml .. _plantuml emacs mode: -------------------------------------------------- :rem:`||:sec:||`\ PlantUML Emacs Mode -------------------------------------------------- There is also a `major mode for editing PlantUML sources in Emacs `_ with preview facilities: .. code-block:: sh wget https://raw.githubusercontent.com/skuro/plantuml-mode/master/plantuml-mode.el This mode is included in the local shared site-lisp. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :rem:`|:sec:|`\ Enable the Major Mode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can automatically enable ``plantuml-mode`` for files with extension ``.plantuml`` by adding the following to your ``.emacsrc``: .. code-block:: elisp ;; Enable plantuml-mode for `PlantUML`_ files (add-to-list 'auto-mode-alist '("\\.plantuml\\'" . plantuml-mode)) Of course, you can always enable manually the major mode by typing ``M-x plantuml-mode`` once in the desired `PlantUML`_ file buffer. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :rem:`|:sec:|`\ Emacs Mode Usage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can tell ``plantuml-mode`` to autocomplete the word before the cursor by typing ``M-x plantuml-complete-symbol``. This will open a popup with all the available completions as found in the list of keywords given by running `PlantUML`_ with the ``-language`` flag. To render the `PlantUML`_ diagram within Emacs, you can hit ``M-x plantuml-preview``. This will run :program:`plantuml`\ (1) and display the result in the ``*PLANTUML-Preview*`` buffer. The format used to render the diagram is automagically chosen from what's supported by your Emacs. It will be one of the following, in order of preference: - SVG - PNG - Unicode ASCII art The diagram will be either created from the selected region if one is available in the current buffer, or using the whole buffer otherwise. If you want to force a specific output format, you can customize the variable ``plantuml-output-type`` to the value you prefer. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :rem:`|:sec:|`\ Default Key Bindings ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following shortcuts are enabled by default: :: C-c C-c plantuml-preview: renders a PlantUML diagram from the current buffer in the best supported format C-u C-c C-c plantuml-preview in other window C-u C-u C-c C-c plantuml-preview in other frame ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :rem:`|:sec:|`\ UMLX ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The python module :ref:`line_diversion` extracts marked annotation lines from source files. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :rem:`|:sec:|`\ Emacs Mode Installation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To enable preview you need to tell ``plantuml-mode`` where to locate the `PlantUML`_ JAR file. By default it will look for it in ``~/plantuml.jar``, but you can specify any location with: :: M-x customize-variable plantuml-jar-path .. _yuml tool: ================================================== :rem:`|||:sec:|||`\ yUML ================================================== `yUML`_ is a web service only, which makes it hard to use offline. There is an `unofficial command line tool for yuml `_ and `sphinx`_ integration `sphinxcontrib-yuml `_. `GitHub - aivarsk/scruffy`_ is an abandoned project that does not use the web service. `yUML`_ provides support for class, activity and usecase diagrams:: .. yuml:: :alt: [Customer]->[Orders] :type: class, activity or usecase :scale: positive integer value :direction: LR, TD or RL (ignored by usecase and activity) :style: nofunky, plain, scruffy [Customer|-forname:string;surname:string|doShiz()]<>-orders*>[Order] [Order]-[note:Aggregate root (nofunky){bg:wheat}] .. .. yuml:: :alt: [Customer]->[Orders] nofunky :type: class :style: nofunky [Customer|-forname:string;surname:string|doShiz()]<>-orders*>[Order] [Order]-[note:Aggregate root (nofunky){bg:wheat}] .. See https://stackoverflow.com/questions/6473660/using-sphinx-docs-how-can-i-specify-png-image-formats-for-html-builds-and-pdf-im and http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#images for usage of image.* .. image:: _static/.cache/yuml-class-nofunky.* :alt: [Customer]->[Orders] nofunky :rem:`space` .. .. yuml:: :alt: [Customer]->[Orders] plain :type: class :style: plain [Customer|-forname:string;surname:string|doShiz()]<>-orders*>[Order] [Order]-[note:Aggregate root (plain){bg:wheat}] .. image:: _static/.cache/yuml-class-plain.* :alt: [Customer]->[Orders] plain :rem:`space` .. .. yuml:: :alt: [Customer]->[Orders] scruffy :type: class :style: scruffy :direction: TD [Customer|-forname:string;surname:string|doShiz()]<>-orders*>[Order] [Order]-[note:Aggregate root (scruffy) {bg:wheat}] .. image:: _static/.cache/yuml-class-scruffy-td.* :alt: [Customer]->[Orders] scruffy :rem:`space` ---- .. .. yuml:: :alt: [Customer]-(Buy Products) :type: usecase :style: plain [Customer]-(Sign In) [Customer]-(Buy Products) (Buy Products)>(Browse Products) (Buy Products)>(Checkout) (Checkout)<(Add New Credit Card) .. image:: _static/.cache/yuml-usecase-plain.* :alt: [Customer]-(Buy Products) ---- .. .. yuml:: :alt: (Make Coffee) :type: activity :style: scruffy (start)->|a|,|a|->(Make Coffee)->|b|,|a|->(Make Breakfast)->|b|,|b|->[want more coffee]->(Make Coffee),[satisfied]->(end) .. image:: _static/.cache/yuml-activity-scruffy.* :alt: (Make Coffee) .. _`GitHub - aivarsk/scruffy`: https://github.com/aivarsk/scruffy -------------------------------------------------- :rem:`||:sec:||`\ Installation -------------------------------------------------- yUML command line tool: .. code-block:: sh easy_install git://github.com/wandernauta/yuml The updated package :command:`python-sphinxcontrib.yuml` is in the local package repository and can be installed with: .. code-block:: sh apt-get install python-sphinxcontrib.yuml See also `njouanin/sphinxcontrib-yuml`_; Manual installation from original sources: .. code-block:: sh wget -q 'https://pypi.python.org/packages/bf/9b/99d1ea03b6199ccd93fbf19b02fe23160b0004b6973d4bd1ef233bd633e2/sphinxcontrib-yuml-0.3.1.tar.gz' tar -zxf sphinxcontrib-yuml-0.3.1.tar.gz ( cd sphinxcontrib-yuml-0.3.1/sphinxcontrib/ || exit 1 patch -p0 <<'EOF' diff -u yuml.orig.py yuml.py --- yuml.orig.py 2013-11-19 22:08:16.000000000 +0100 +++ yuml.py 2018-04-09 10:47:29.740133938 +0200 @@ -15,6 +15,7 @@ from os import path from docutils import nodes from docutils.parsers.rst import directives +import docutils.parsers.rst.directives.images from sphinx.errors import SphinxError from sphinx.util import ensuredir, relative_uri try: @@ -48,13 +49,13 @@ :type: class, activity or usecase :scale: positive integer value :direction: LR, TD or RL - :style: boring, plain, scruffy + :style: nofunky, plain, scruffy [Customer]->[Billing Address] """ type_values = ('class', 'activity', 'usecase') direction_values = ('LR', 'RL', 'TD') - style_values=('boring', 'plain', 'scruffy') + style_values=('nofunky', 'plain', 'scruffy') def type_choice(argument): return directives.choice(argument, YumlDirective.type_values) EOF cp yuml.py /usr/lib/python2.7/dist-packages/sphinxcontrib/ ) .. _`yUML`: https://yuml.me/ .. _`njouanin/sphinxcontrib-yuml`: https://github.com/njouanin/sphinxcontrib-yuml ================================================== :rem:`|||:sec:|||`\ Other UML Tools ================================================== Other interesting `UML`_ tools by category. -------------------------------------------------- :rem:`|:sec:|`\ Declarative -------------------------------------------------- - `yUML`_ is a web service. - `UMLGraph `_ Class diagrams: Java syntax, Javadoc integration, :command:`umlgraph` -> :command:`dot` -> image. Sequence diagrams: :command:`pic` macros -> :command:`pic2plot` -> image. .. _gui tools with uml standard support: -------------------------------------------------- :rem:`|:sec:|`\ GUI with UML standard support -------------------------------------------------- According to the `list of Unified Modeling Language tools on Wikipedia`_, The most recently active projects are - `UML Designer`_ (Eclipse) best handling - `Papyrus`_ (Eclipse) - `BOUML - a free UML tool box`_ has a python generator (free of use) - `Modelio Open Source - UML and BPMN free modeling tool`_ (no SVG?) - `Umbrello `_ (package :command:`Umbrello`) `UML`_ standard support, `XMI`_ file format, image export. - `UMLet `_ (package :command:`umlet`) Freeform diagrams, proprietary XML file format, image export. Java auto generator support. - :command:`ArgoUML` (UML 1.4) `UML`_ standard support, `XMI`_ file format, image export. .. _`list of Unified Modeling Language tools on Wikipedia`: https://en.wikipedia.org/wiki/List_of_Unified_Modeling_Language_tools .. _`BOUML - a free UML tool box`: http://www.bouml.fr/ .. _`Modelio Open Source - UML and BPMN free modeling tool`: https://www.modelio.org/ .. _`Papyrus`: http://www.eclipse.org/papyrus/ .. _`UML Designer`: http://www.umldesigner.org/ -------------------------------------------------- :rem:`|:sec:|`\ Generic Diagrams -------------------------------------------------- - `Dia `_ (package :command:`dia`), Freeform diagrams, proprietary compressed XML format. Image, :command:`dot`, Visio export. .. _auto generators: -------------------------------------------------- :rem:`|:sec:|`\ Auto generators -------------------------------------------------- - :command:`gen_plantuml.py` based on the GitHubGist `generate PlantUML definition from python sources`_. - :command:`pyreverse` (from package `pylint `_), :command:`python` -> :command:`dot`. Generating a `PlantUML`_ definition of global variables and functions can also be as simple as: .. code-block:: python :linenos: class_name = 'global' func_type = type(run) func_type_builtin = type(issequence) module_type = type(os) globals_ = globals() public = globals_.get('__all__', []) if not public: public = list(dkeys(globals_)) items = [] items.extend(((_sym, _val, '-') for _sym, _val in sorted(ditems(globals_)) if _sym not in public)) items.extend(((_sym, globals_[_sym], '+') for _sym in public)) opt_all_syms = None classes = [] variables = [] functions = [] for _sym, _val, _visibility in items: if not opt_all_syms: if _sym.startswith('_'): continue if _sym.startswith('__') and _sym.endswith('__'): continue if isinstance(_val, module_type): continue if isinstance(_val, type): classes.append((_sym, _val, _visibility)) continue if isinstance(_val, (func_type, func_type_builtin)): _list = functions _sfx = '()' else: _list = variables _sfx = '' _list.append(sformat('{0} : {1}{2}{3}', class_name, _visibility, _sym, _sfx)) printf(sformat(' class {0} << (G, #FFCCCC) >>', class_name)) for _list in variables, functions: printf('\n'.join((' ' + _e for _e in _list))) Or as fancy as: .. code-block:: python :linenos: PARENTHESES = dict(( ('(', ')'), ('[', ']'), ('{', '}'), ('<', '>'), ('<<', '>>'), ('|', '|'), (' ', ' '), ('"', '"'), ("'", "'"), )) __all__.append('enclose') def enclose(elt, open=None, close=None, sep=None, forced=None): # ||:fnc:|| r"""enclose string in parenthesis. :returns: enclosed string :param elt: element to be enclosed :param open: opening parenthesis (default: `(`) :param close: closing parenthesis (default: :data:`PARENTHESIS`.get(open, '') :param sep: separator after open and before close, (default: '') :param forced: add parentheses, even if they already exist. >>> printf(enclose('abc')) (abc) >>> printf(enclose('(abc')) (abc) >>> printf(enclose('abc)')) (abc) >>> printf(enclose('(abc)')) (abc) >>> printf(enclose('(abc)', forced=True)) ((abc)) >>> printf(enclose('abc', '<<')) <> >>> printf(enclose(enclose('abc', ' '), '<<')) << abc >> >>> printf(enclose('abc', '-| ')) -| abc """ if open is None: open = '(' if close is None: close = PARENTHESES.get(open, '') if sep is None: sep = '' enclosed = [] if forced or (open and not re.match('\\s*' + re.escape(open), elt)): enclosed.append(open) if open: enclosed.append(sep) enclosed.append(elt) if forced or (close and not re.search(re.escape(close) + '\\s*$', elt)): if close: enclosed.append(sep) enclosed.append(close) return ''.join(enclosed) __all__.append('join_lists_flatten') def join_lists_flatten(lists, sep): # ||:fnc:|| r"""Insert separator between elements of a list. :returns: list where each group of elements is separated from the next group of element with `sep`. :param lists: a list of element groups (lists). All elements of group are appended as single elements to the result list. :param sep: separater inserted betwwen two groups of elements. """ result = [] if lists: result.extend(lists[0]) for _list in lists[1:]: result.append(sep) result.extend(_list) return result __all__.append('plantuml_format_class') def plantuml_format_class(name, sections=None, circle=None, stereotype=None, alias=None, sep=None): # ||:fnc:|| r""" :returns: class formatted for a `PlantUML`_ class diagram. :param name: class name :param sections: list of class sections, each section is a list of attribute/operation lines. :param circle: :param stereotype: :param alias: class alias .. _`PlantUML`: http://plantuml.com """ if sections is None: sections = [] formatted = [] _class_param = [] if circle and circle.strip(): _class_param.append(enclose(circle, '(')) if stereotype and stereotype.strip(): _class_param.append(stereotype) class_param = ' '.join(_class_param) if class_param: class_param = enclose(class_param, '<<', sep=' ') if alias: name = enclose(name, '"') class_alias = 'as ' + alias else: class_alias = '' if sep is None: sep = '' formatted.append(sformat('class {0} {{', ' '.join((_s for _s in (name, class_alias, class_param) if _s)))) _first = True for _list in sections: if _list: if _first: _first = False else: formatted.append(' ' + sep) formatted.extend((' ' + _e for _e in _list)) formatted.append('}') return '\n'.join(formatted) class_name = 'global' func_type = type(run) func_type_builtin = type(issequence) module_type = type(os) globals_ = globals() public = globals_.get('__all__', []) if not public: public = list(dkeys(globals_)) items = [] items.extend(((_sym, _val, '-') for _sym, _val in sorted(ditems(globals_)) if _sym not in public)) items.extend(((_sym, globals_[_sym], '+') for _sym in public)) opt_all_syms = None import pyjsmo classes = [] variables = pyjsmo.OrderedDict(( ('-', []), ('+', []), )) functions = pyjsmo.OrderedDict(( ('-', []), ('+', []), )) for _sym, _val, _visibility in items: if not opt_all_syms: if _sym.startswith('_'): continue if _sym.startswith('__') and _sym.endswith('__'): continue if isinstance(_val, module_type): continue if isinstance(_val, type): classes.append((_sym, _val, _visibility)) continue if isinstance(_val, (func_type, func_type_builtin)): _list = functions[_visibility] _sfx = '()' else: _list = variables[_visibility] _sfx = '' _list.append(sformat('{0}{1}{2}', _visibility, _sym, _sfx)) variables = join_lists_flatten([_v for _v in dvalues(variables) if _v], '..') functions = join_lists_flatten([_v for _v in dvalues(functions) if _v], '..') printf(plantuml_format_class(class_name, (variables, functions), circle='G, #FFCCCC', sep='--', alias='G')) ================================================== :rem:`|||:sec:|||`\ Summary ================================================== - UML is the abbreviation of unified modeling language. It is a standarizied method for descriping programms. - The UML diagrams are easy to understand even for noprogrammers - There are existing some UML GUI-TOOLS. There are good for noprogrammers to modeling something, but programmers should'nt use them, because the not-diagram-output is'nt readable for a human. And if the output is not readable, it needs more effort to write or update a documentation (you would need every time this GUI-Tool if you want to know what happends in the programm via UML, without the GUI-TOOL, the output is worthless) - Programmers should use `PlantUML`_ to create UML diagrams. - `PlantUML`_ is a open source tool, which uses a certain syntax to create a UML diagram - Programmers don't need the diagram output, to get an accurate overview of the programm, because it is quite easy to understand the associations of the programm if you look at the `PlantUML`_ syntax - `PlantUML`_ is already integrated in a lot of tools (for instance emacs, sphinx), so you can write your `PlantUML`_ code in for example in your python script as a commend, and emacs can show you the diagram with a shortcut. - A class diagram (similar to entity relationship diagrams for databases) shows boxes for class, interface, annotation, enum, ... The upper section shows attributes, the lower section contains operations (methods). - every class in it's own box, globals in a own box - different types of interfaces: - Association -- is independent (no owner) (students, teacher) - Aggregation o-- independent, no owner (department, teacher) - Composition \*__ death relationsship, if parent dies, all children will die too (kettle and tableau) - Sequence Diagram Shows the message flow between several participants of a system on timelines. - Activity Diagram (in German known as "Aktivitätsdiagramm") -------------------------------------------------- :rem:`||:sec:||`\ Object diagram with dot(1) -------------------------------------------------- Why dot(1) is not so useful for object diagrams. .. graphviz:: digraph "TCP connection" { // rankdir=LR; Client [shape=plaintext,label=<
Client
NIC
IP address
netmask
>,style=solid]; Server [shape=plaintext,label=<
Server
NIC
IP address
netmask
>,style=solid]; // ⏵ // ▶ // ⯈ Client:NIC -> Server:NIC [label="connects >"]; Client:NIC -> Server:NIC [label="sends\nrequest >"]; Server:NIC -> Client:NIC [label="sends\nresponse >"]; } .. >>CODD Conclusion .. >>CODD Appendix A .. \|:here:| .. >>CODD Notes .. ================================================== .. :rem:`|||:sec:|||`\ Footnotes .. ================================================== :html:`
` .. [#] As long as programmers maintain documentation, it will always be more or less out of date. When documentation is decoupled from a program it is nothing but guaranteed to be become incorrect. .. include:: doc_defs.inc .. include:: doc_defs_combined.inc .. include:: abbrev_defs.inc .. .. \||<-snap->|| doc_standalone .. include:: doc/doc_defs_secret.inc .. \||<-snap->|| doc_standalone .. \||<-snap->|| not_doc_standalone .. include:: doc_defs_secret.inc .. \||<-snap->|| not_doc_standalone .. _`Wolfgang Scherer`: wolfgang.scherer@gmx.de