Added aliases, realigned documentation, progressed readme

skleanthous · Mar 11, 2019 · b937803 · b937803
1 parent e96a2d5
commit b937803
Show file tree

Hide file tree

Showing 14 changed files with 124 additions and 52 deletions.
diff --git a/README.md b/README.md
@@ -43,7 +43,27 @@ This tool allows you to use stereotypes to skin your diagram to be close to what
 1. Dynamic diagram
 1. Dynamic diagram
 
+## Examples
+---
+
+Reproduced (as closely as possible from diagrams from [the official C4 model website](https://c4model.com/))
+
+1. System Context diagram
+
+    [PlantUml file for diagram below](./sample/c4-banking-system.puml)
+
+    ![System Context Fiagram](./sample/c4-banking-system.png)
+
+2. Container diagram
 
+    [PlantUml file for diagram below](./sample/c4-banking-container.puml)
+
+    ![Container diagram](./sample/c4-banking-container.png)
+
+3. Component diagram
+
+    ## _**!!!TODO!!!**_
+
 ## Instructions
 ---
 
@@ -61,7 +81,7 @@ All that is needed to start is to add the following line:
 
     As mentioned above, the way that you would skin your artifacts is through the use of stereotyping. Due to this, currently stereotype names are not emitted, but instead, a legend is emited on the bottom right. At this time it cannot be turned off.
 
-1. ### C4 Person <--> PlantUml Actors
+2. ### Represent C4 Person --> with PlantUml Actors
 
     There is support for two types of actors. Internal and external actors. The supported stereotypes are:
     - `<<Internal>>`
@@ -91,55 +111,47 @@ All that is needed to start is to add the following line:
 
     ![Actors](./docs/diagrams/actors.png)
 
-1. ### C4 Systems <---> PlantUml Rectangles and Frames
+3. #### Represent C4 Systems --> with PlantUml Rectangles and Frames
 
-    C4 Systems can be reprensented using PlantUml rectangles and frames. In both cases the stereotype that should be used are:
+    C4 Systems can be reprensented using PlantUml rectangles and frames. In both cases the stereotypes that could be used are:
+
+    > **NOTE**: the simplicity of rectangles makes them really useful if you want to avoid the connotations implied by UML artifacts, so they are used to represent other C4 artifacts too
 
     - `<<Internal System>>`
-    - `<<System>>` an alias to `<<Internal System>>`
+    - `<<System>>` (an alias to `<<Internal System>>`)
     - `<<External System>>`
 
     The following code:
 
-    ```
-
-1. ### PlantUml Components <--> C4 Containers
-
-    PlantUml components can represent containers (and not C4 components which is a bit confusing), which are useful to be shown normally on `System Context`, `Container` and `System Landscape` diagrams. The supported stereotypes are:
-    
-    - `<<Internal Container>>`
-    - `<<External Container>>`
-
-    The following code:
-
     ```plantumlcode
     @startuml
     !define NO_LEGEND
 
     !includeurl https://raw.githubusercontent.com/skleanthous/C4-PlantumlSkin/master/build/output/c4.puml
 
-    component Internal <<Internal Container>>
-    component External <<External Container>>
+    rectangle Internal <<Internal System>>
+    frame AnotherInternal <<System>>
+    rectangle External <<External System>>
+    frame AnotherExternal <<External System>>
 
     Internal -right-> External
+    Internal -[hidden]down-> AnotherInternal
+    AnotherInternal -right-> AnotherExternal
 
-    @end    
+    @enduml
     ```
 
-    Produces this outcome:
-
-    ![Containers](./docs/diagrams/containers.png)
+    Produces the outcome:
 
-2. ## PlantUml Rectangles <--> C4 Systems and Components
+    ![Systems](./docs/diagrams/systems.png)
 
-    PlantUml rectangles can represent C4 systems and components. The supported stereotypes are:
+4. #### Represent C4 Containers --> with PlantUml Rectangle and Components
 
-    - `<<Internal System>>`
-    - `<<External System>>`
-    - `<<Internal Component>>`
-    - `<<External Component>>`
-
-    Systems and Components render the same way (as rectangles). Internal systems and components have a slightly different background color to be easir to read.
+    C4 containers can be repesented by using plantuml rectangles  (and not C4 components which is a bit confusing), which are useful to be shown normally on `System Context`, `Container` and `System Landscape` diagrams. The supported stereotypes are:
+
+    - `<<Internal Container>>`
+    - `<<Container>>` (an alias to `Internal Container`)
+    - `<<External Container>>`
 
     The following code:
 
@@ -149,18 +161,32 @@ All that is needed to start is to add the following line:
 
     !includeurl https://raw.githubusercontent.com/skleanthous/C4-PlantumlSkin/master/build/output/c4.puml
 
-    rectangle Internal <<Internal System>>
-    rectangle External <<External System>>
+    component InternalComponent <<Internal Container>>
+    component ExternalComponent <<External Container>>
+
+    rectangle InternalRectangle <<Internal Container>>
+    rectangle ExternalRectangle <<External Container>>
+
+    InternalComponent -right-> ExternalComponent
+    InternalComponent -[hidden]down-> InternalRectangle
+    InternalRectangle -right-> ExternalRectangle
 
-    Internal --> External
     @enduml
     ```
 
     Produces this outcome:
 
-    ![Systems](./docs/diagrams/systems.png)
+    ![Containers](./docs/diagrams/containers.png)
 
-    While this plantuml code:
+5. #### Represent C4 components --> with PlantUml rectangles
+
+    C4 components can currently only be represented by plantuml rectangles. The are only really usesful in `Component` C4 diagrams, but obviously really important. The stereotypes used 
+
+    - `<<Internal Component>>`
+    - `<<Component>>` (an alias to `<<Internal Component>>`)
+    - `<<External Component>>`
+
+    The following code:
 
     ```plantumlcode
     @startuml
@@ -171,17 +197,27 @@ All that is needed to start is to add the following line:
     rectangle Internal <<Internal Component>>
     rectangle External <<External Component>>
 
-    Internal --> External
+    Internal -right-> External
+
     @enduml
     ```
 
     Produces this outcome:
 
     ![Components](./docs/diagrams/components.png)
 
-3. ### More details
+6. #### More details
+
+    The above should be enough to get you started. For more info please see:
+
+    - [Items definitions](./src/items)
+    - [PlantUml files for the sample diagrams](./sample/)
+    - [List of all supported artifacts](./docs/diagrams/)
+
+## work outstanding
 
-    For more details, please [visit the docs](./docs/readme.md)
+1. Complete examples
+1. Add skinning for C4 Code diagrams 
 
 ## Inspiration \ Acknowledgements
 ---

diff --git a/build/output/items/components.puml b/build/output/items/components.puml
@@ -16,3 +16,9 @@ skinparam rectangle<<Internal Component>> {
   BackgroundColor COMPONENT_BG_COLOR
 }
 
+
+skinparam rectangle<<Component>> {
+  FontColor COMPONENT_FONT_COLOR
+  BorderColor INTERNAL_BORDER_COLOR
+  BackgroundColor COMPONENT_BG_COLOR
+}
diff --git a/build/output/items/containers.puml b/build/output/items/containers.puml
@@ -16,6 +16,12 @@ skinparam component<<Internal Container>> {
   BackgroundColor CONTAINER_BG_COLOR
 }
 
+skinparam component<<Container>> {
+  FontColor CONTAINER_FONT_COLOR
+  BorderColor CONTAINER_BORDER_COLOR
+  BackgroundColor CONTAINER_BG_COLOR
+}
+
 skinparam rectangle<<External Container>> {
   FontColor CONTAINER_FONT_COLOR
   BorderColor EXTERNAL_CONTAINER_BORDER_COLOR
@@ -26,4 +32,10 @@ skinparam rectangle<<Internal Container>> {
   FontColor CONTAINER_FONT_COLOR
   BorderColor CONTAINER_BORDER_COLOR
   BackgroundColor CONTAINER_BG_COLOR
+}
+
+skinparam rectangle<<Container>> {
+  FontColor CONTAINER_FONT_COLOR
+  BorderColor CONTAINER_BORDER_COLOR
+  BackgroundColor CONTAINER_BG_COLOR
 }
diff --git a/build/output/items/dbs.puml b/build/output/items/dbs.puml
@@ -18,7 +18,7 @@ skinparam database<<Internal Database>> {
 
 skinparam database<<External>> {
   BackgroundColor EXTERNAL_CONTAINER_BG_COLOR
-  BorderColor EXTERNAL_BORDER_COLOR
+  BorderColor EXTERNAL_CONTAINER_BORDER_COLOR
   FontColor CONTAINER_FONT_COLOR
 }
 

diff --git a/docs/diagrams/actors.puml b/docs/diagrams/actors.puml
@@ -1,7 +1,7 @@
 @startuml
 !define NO_LEGEND
 
-!include ../../src/c4.puml
+!includeurl https://raw.githubusercontent.com/skleanthous/C4-PlantumlSkin/master/build/output/c4.puml
 
 actor Internal <<Internal>>
 actor External <<External>>

diff --git a/docs/diagrams/components.png b/docs/diagrams/components.png
diff --git a/docs/diagrams/components.puml b/docs/diagrams/components.puml
@@ -1,11 +1,11 @@
 @startuml
 !define NO_LEGEND
 
-!include ../../src/c4.puml
+!includeurl https://raw.githubusercontent.com/skleanthous/C4-PlantumlSkin/master/build/output/c4.puml
 
 rectangle Internal <<Internal Component>>
 rectangle External <<External Component>>
 
-Internal --> External
+Internal -right-> External
 
 @enduml
diff --git a/docs/diagrams/containers.png b/docs/diagrams/containers.png
diff --git a/docs/diagrams/containers.puml b/docs/diagrams/containers.puml
@@ -1,16 +1,16 @@
 @startuml
 !define NO_LEGEND
 
-!include ../../src/c4.puml
+!includeurl https://raw.githubusercontent.com/skleanthous/C4-PlantumlSkin/master/build/output/c4.puml
 
-component Internal <<Internal Container>>
-component External <<External Container>>
+component InternalComponent <<Internal Container>>
+component ExternalComponent <<External Container>>
 
 rectangle InternalRectangle <<Internal Container>>
 rectangle ExternalRectangle <<External Container>>
 
-Internal -right-> External
-Internal -[hidden]down-> InternalRectangle
+InternalComponent -right-> ExternalComponent
+InternalComponent -[hidden]down-> InternalRectangle
 InternalRectangle -right-> ExternalRectangle
 
 @enduml
diff --git a/docs/diagrams/systems.png b/docs/diagrams/systems.png
diff --git a/docs/diagrams/systems.puml b/docs/diagrams/systems.puml
@@ -1,15 +1,15 @@
 @startuml
 !define NO_LEGEND
 
-!include ../../src/c4.puml
+!includeurl https://raw.githubusercontent.com/skleanthous/C4-PlantumlSkin/master/build/output/c4.puml
 
 rectangle Internal <<Internal System>>
 frame AnotherInternal <<System>>
 rectangle External <<External System>>
-frame ExternalFrame <<External System>>
+frame AnotherExternal <<External System>>
 
-Internal -right-> AnotherInternal
-Internal -[hidden]down-> External
-External -right-> ExternalFrame
+Internal -right-> External
+Internal -[hidden]down-> AnotherInternal
+AnotherInternal -right-> AnotherExternal
 
 @enduml
diff --git a/src/items/components.puml b/src/items/components.puml
@@ -16,3 +16,9 @@ skinparam rectangle<<Internal Component>> {
   BackgroundColor COMPONENT_BG_COLOR
 }
 
+
+skinparam rectangle<<Component>> {
+  FontColor COMPONENT_FONT_COLOR
+  BorderColor INTERNAL_BORDER_COLOR
+  BackgroundColor COMPONENT_BG_COLOR
+}
diff --git a/src/items/containers.puml b/src/items/containers.puml
@@ -16,6 +16,12 @@ skinparam component<<Internal Container>> {
   BackgroundColor CONTAINER_BG_COLOR
 }
 
+skinparam component<<Container>> {
+  FontColor CONTAINER_FONT_COLOR
+  BorderColor CONTAINER_BORDER_COLOR
+  BackgroundColor CONTAINER_BG_COLOR
+}
+
 skinparam rectangle<<External Container>> {
   FontColor CONTAINER_FONT_COLOR
   BorderColor EXTERNAL_CONTAINER_BORDER_COLOR
@@ -26,4 +32,10 @@ skinparam rectangle<<Internal Container>> {
   FontColor CONTAINER_FONT_COLOR
   BorderColor CONTAINER_BORDER_COLOR
   BackgroundColor CONTAINER_BG_COLOR
+}
+
+skinparam rectangle<<Container>> {
+  FontColor CONTAINER_FONT_COLOR
+  BorderColor CONTAINER_BORDER_COLOR
+  BackgroundColor CONTAINER_BG_COLOR
 }
diff --git a/src/items/dbs.puml b/src/items/dbs.puml
@@ -18,7 +18,7 @@ skinparam database<<Internal Database>> {
 
 skinparam database<<External>> {
   BackgroundColor EXTERNAL_CONTAINER_BG_COLOR
-  BorderColor EXTERNAL_BORDER_COLOR
+  BorderColor EXTERNAL_CONTAINER_BORDER_COLOR
   FontColor CONTAINER_FONT_COLOR
 }