1.3.3.9. Sphinx Diagram Directives (PlantUML)

  • Requirements:

    • Install: sphinxcontrib-plantuml via Python pip (Included in SPHINX_ENV_INSTALL, Sphinx Environment)

    • Copy graphviz-2.38 folder to / (Included in SPHINX_ENV_INSTALL, Sphinx Environment via install.sh)

    • Copy plantuml.jar to /java (Included in SPHINX_ENV_INSTALL, Sphinx Environment via install.sh)

    • Configure environment for plantuml and graphviz (Included in SPHINX_ENV_INSTALL, Sphinx Environment via install.sh and install.bat)

This is your .rst file code example to create PlantUML Diagram(s) http://plantuml.com/:

Table 1.10 PlantUML Options

Option

Values

:align:

left, center or right

:scale:

0-100 percentage value

:caption:

text to label Figure

  • Example 01

    .. uml::
    :scale: 75
    :align: center
    :caption: plantuml_example01

    Alice -> Bob: Hi!
    Alice <- Bob: How are you?

    Rendered

    Alice -> Bob: Hi! Alice <- Bob: How are you?

    Figure 1.8 plantuml_example01

  • Example 02

    .. uml::
    :scale: 75
    :align: center
    :caption: plantuml_example02

    Foo <|-- Bar

    Rendered

    Foo <|-- Bar

    Figure 1.9 plantuml_example02

  • Example 03

    Note

    Using @startuml and @enduml is not required but is proper formatting to move easily to a .uml file later.

    .. uml::
    :scale: 75
    :align: center
    :caption: plantuml_example03

    @startuml

    'style options
    skinparam monochrome true
    skinparam circledCharacterRadius 0
    skinparam circledCharacterFontSize 0
    skinparam classAttributeIconSize 0
    hide empty members

    Class01 <|-- Class02
    Class03 *-- Class04
    Class05 o-- Class06
    Class07 .. Class08
    Class09 -- Class10

    @enduml

    Rendered

    @startuml 'style options skinparam monochrome true skinparam circledCharacterRadius 0 skinparam circledCharacterFontSize 0 skinparam classAttributeIconSize 0 hide empty members Class01 <|-- Class02 Class03 *-- Class04 Class05 o-- Class06 Class07 .. Class08 Class09 -- Class10 @enduml

    Figure 1.10 plantuml_example03

  • Example 04

    .. uml:: plantuml_example04.uml
    :scale: 75
    :align: center
    :caption: plantuml_example04

    Rendered (From loading .uml file)

    @startuml salt { Just plain text [This is my button] () Unchecked radio (X) Checked radio [] Unchecked box [X] Checked box "Enter text here " ^This is a droplist^ } @enduml

    Figure 1.11 plantuml_example04

  • Example 05

    Code 1.3 plantuml_example05.uml
    @startuml

'style options
skinparam monochrome true
skinparam circledCharacterRadius 0
skinparam circledCharacterFontSize 0
skinparam classAttributeIconSize 0
hide empty members

class Car

Driver - Car : drives >
Car *- Wheel : have 4 >
Car -- Person : < owns

@enduml

    Rendered (From loading .uml file - same as Example04 just different file)

    @startuml 'style options skinparam monochrome true skinparam circledCharacterRadius 0 skinparam circledCharacterFontSize 0 skinparam classAttributeIconSize 0 hide empty members class Car Driver - Car : drives > Car *- Wheel : have 4 > Car -- Person : < owns @enduml

    Figure 1.12 plantuml_example05

  • Example 06

    Code 1.4 plantuml_example06.uml
    @startuml

'style options
skinparam monochrome true
skinparam circledCharacterRadius 9
skinparam circledCharacterFontSize 8
skinparam classAttributeIconSize 0
hide empty members

abstract class AbstractClass {
- privateField
+ publicField
# protectedField
~ packagePrivateField
- privateMethod()
+ publicMethod()
# protectedMethod()
~ packagePrivateMethod()
 }

class Dummy {
{static} staticID
{abstract} void methods()
 }

class Flight {
 flightNumber : Integer
 departureTime : Date
 }

package "Classic Collections" {

 abstract class AbstractList
 abstract AbstractCollection
 interface List
 interface Collection

 List <|-- AbstractList
 Collection <|-- AbstractCollection

 Collection <|- List
 AbstractCollection <|- AbstractList
 AbstractList <|-- ArrayList

 class ArrayList {
   Object[] elementData
   size()
    }
}

enum TimeUnit {
DAYS
HOURS
MINUTES
}


class Student {
Name
}
Student "0..*" -- "1..*" Course
(Student, Course) .. Enrollment

class Enrollment {
drop()
cancel()
}

@enduml

    Rendered (From loading .uml file - same as Example04 just different file)

    @startuml 'style options skinparam monochrome true skinparam circledCharacterRadius 9 skinparam circledCharacterFontSize 8 skinparam classAttributeIconSize 0 hide empty members abstract class AbstractClass { - privateField + publicField # protectedField ~ packagePrivateField - privateMethod() + publicMethod() # protectedMethod() ~ packagePrivateMethod() } class Dummy { {static} staticID {abstract} void methods() } class Flight { flightNumber : Integer departureTime : Date } package "Classic Collections" { abstract class AbstractList abstract AbstractCollection interface List interface Collection List <|-- AbstractList Collection <|-- AbstractCollection Collection <|- List AbstractCollection <|- AbstractList AbstractList <|-- ArrayList class ArrayList { Object[] elementData size() } } enum TimeUnit { DAYS HOURS MINUTES } class Student { Name } Student "0..*" -- "1..*" Course (Student, Course) .. Enrollment class Enrollment { drop() cancel() } @enduml

    Figure 1.13 plantuml_example06

  • Example 07

    Code 1.5 plantuml_example07.uml
    @startuml
actor "Main Database" as DB << Application >>

note left of DB
  This actor
  has a "name with spaces",
  an alias
  and a stereotype
end note

actor User << Human >>
actor SpecialisedUser
actor Administrator

User <|--- SpecialisedUser
User <|--- Administrator

usecase (Use the application) as (Use) << Main >>
usecase (Configure the application) as (Config)
Use ..> Config : <<includes>>

User --> Use
DB --> Use

Administrator --> Config

note "This note applies to\nboth actors." as MyNote
MyNote .. Administrator
MyNote .. SpecialisedUser

'  this is a text comment and won't be displayed
AnotherActor ---> (AnotherUseCase)

'  to increase the length of the edges, just add extras dashes, like this:
ThirdActor ----> (LowerCase)

'  The direction of the edge can also be reversed, like this:
(UpperCase) <---- FourthActor

@enduml

    Rendered (From loading .uml file - same as Example04 just different file)

    @startuml actor "Main Database" as DB << Application >> note left of DB This actor has a "name with spaces", an alias and a stereotype end note actor User << Human >> actor SpecialisedUser actor Administrator User <|--- SpecialisedUser User <|--- Administrator usecase (Use the application) as (Use) << Main >> usecase (Configure the application) as (Config) Use ..> Config : <<includes>> User --> Use DB --> Use Administrator --> Config note "This note applies to\nboth actors." as MyNote MyNote .. Administrator MyNote .. SpecialisedUser ' this is a text comment and won't be displayed AnotherActor ---> (AnotherUseCase) ' to increase the length of the edges, just add extras dashes, like this: ThirdActor ----> (LowerCase) ' The direction of the edge can also be reversed, like this: (UpperCase) <---- FourthActor @enduml

    Figure 1.14 plantuml_example07

  • Example 08

    Code 1.6 plantuml_example08.uml
    @startuml

start

:first activity;

:second activity
with a multiline
and rather long description;

:another activity;

note right
 After this activity,
 are two 'if-then-else' examples.
end note

if (do optional activity?) then (yes)
  :optional activity;
else (no)

  if (want to exit?) then (right now!)
     stop
  else (not really)

  endif

endif

:third activity;

note left
 After this activity,
 parallel activities will occur.
end note

fork
  :Concurrent activity A;
fork again
  :Concurrent activity B1;
  :Concurrent activity B2;
fork again
  :Concurrent activity C;
  fork
  :Nested C1;
  fork again
  :Nested C2;
  end fork
end fork

repeat
  :repetitive activity;
repeat while (again?)

while (continue?) is (yes, of course)
 :first activity inside the while loop;
 :second activity inside the while loop;
endwhile (no)

stop

@enduml

    Rendered (From loading .uml file - same as Example04 just different file)

    @startuml start :first activity; :second activity with a multiline and rather long description; :another activity; note right After this activity, are two 'if-then-else' examples. end note if (do optional activity?) then (yes) :optional activity; else (no) if (want to exit?) then (right now!) stop else (not really) endif endif :third activity; note left After this activity, parallel activities will occur. end note fork :Concurrent activity A; fork again :Concurrent activity B1; :Concurrent activity B2; fork again :Concurrent activity C; fork :Nested C1; fork again :Nested C2; end fork end fork repeat :repetitive activity; repeat while (again?) while (continue?) is (yes, of course) :first activity inside the while loop; :second activity inside the while loop; endwhile (no) stop @enduml

    Figure 1.15 plantuml_example08

  • Example 09

    Code 1.7 plantuml_example09.uml
    @startuml

[*] --> MyState
MyState --> CompositeState
MyState --> AnotherCompositeState
MyState --> WrongState

CompositeState --> CompositeState : \ this is a loop
AnotherCompositeState --> [*]
CompositeState --> [*]

MyState : this is a string
MyState : this is another string

state CompositeState {

[*] --> StateA : begin something
StateA --> StateB : from A to B
StateB --> StateA : from B back to A
StateB --> [*] : end it

CompositeState : yet another string
}

state AnotherCompositeState {

[*] --> ConcurrentStateA
ConcurrentStateA --> ConcurrentStateA

--

[*] --> ConcurrentStateB
ConcurrentStateB --> ConcurrentStateC
ConcurrentStateC --> ConcurrentStateB
}

note left of WrongState
  This state
  is a dead-end
  and shouldn't
  exist.
end note

@enduml

    Rendered (From loading .uml file - same as Example04 just different file)

    @startuml [*] --> MyState MyState --> CompositeState MyState --> AnotherCompositeState MyState --> WrongState CompositeState --> CompositeState : \ this is a loop AnotherCompositeState --> [*] CompositeState --> [*] MyState : this is a string MyState : this is another string state CompositeState { [*] --> StateA : begin something StateA --> StateB : from A to B StateB --> StateA : from B back to A StateB --> [*] : end it CompositeState : yet another string } state AnotherCompositeState { [*] --> ConcurrentStateA ConcurrentStateA --> ConcurrentStateA -- [*] --> ConcurrentStateB ConcurrentStateB --> ConcurrentStateC ConcurrentStateC --> ConcurrentStateB } note left of WrongState This state is a dead-end and shouldn't exist. end note @enduml

    Figure 1.16 plantuml_example09

  • Example 10

    Code 1.8 plantuml_example10.uml
    @startuml
folder folder [
This is an <b>folder
----
You can use separator
====
of different kind
....
and style
]

node node [
This is a <b>node
----
You can use separator
====
of different kind
....
and style
]

database database [
This is a <b>database
----
You can use separator
====
of different kind
....
and style
]

usecase usecase [
This is a <b>usecase
----
You can use separator
====
of different kind
....
and style
]
@enduml

    Rendered (From loading .uml file - same as Example04 just different file)

    @startuml folder folder [ This is an <b>folder ---- You can use separator ==== of different kind .... and style ] node node [ This is a <b>node ---- You can use separator ==== of different kind .... and style ] database database [ This is a <b>database ---- You can use separator ==== of different kind .... and style ] usecase usecase [ This is a <b>usecase ---- You can use separator ==== of different kind .... and style ] @enduml

    Figure 1.17 plantuml_example10

  • Example 11

    Code 1.9 plantuml_example11.uml
    @startsalt
{
  Login    | "MyName   "
  Password | "****     "
  [Cancel] | [  OK   ]
}
@endsalt

    Rendered (From loading .uml file - same as Example04 just different file)

    @startsalt { Login | "MyName " Password | "**** " [Cancel] | [ OK ] } @endsalt

    Figure 1.18 plantuml_example11

  • Example 12

    Code 1.10 plantuml_example12.uml
    @startsalt
{
{T
 + World
 ++ America
 +++ Canada
 +++ USA
 ++++ New York
 ++++ Boston
 +++ Mexico
 ++ Europe
 +++ Italy
 +++ Germany
 ++++ Berlin
 ++ Africa
}
}
@endsalt

    Rendered (From loading .uml file - same as Example04 just different file)

    @startsalt { {T + World ++ America +++ Canada +++ USA ++++ New York ++++ Boston +++ Mexico ++ Europe +++ Italy +++ Germany ++++ Berlin ++ Africa } } @endsalt

    Figure 1.19 plantuml_example12