final polishing for version 0.8.3, which will be a release.

first step for pumla_project_config.puml file to be used to have a project-specific override of the pumla_global_cfg.puml file values. first test files to play with C4-PlantUML. Extended installation description.
DrMarkusVoss · Sep 23, 2021 · 2a69cab · 2a69cab
1 parent dbee3b1
commit 2a69cab
Show file tree

Hide file tree

Showing 19 changed files with 153 additions and 47 deletions.
diff --git a/README.md b/README.md
@@ -52,11 +52,12 @@ with other applications and documents during software development.
 Of course you need to have `pumla` installed. See further below for 
 installation instructions.
 
-Create a folder for the example. Change into that folder.
-Call `pumla init`. A file called `pumla_macros.puml` should
+Then:
+- Create a folder for the example.
+- Change into that folder. 
+- Call `pumla init`. A file called `pumla_macros.puml` should
 have been created in the folder.
-
-Then create a file like this:
+- Create a file like this:
 
 File: simpleElement.puml
 
@@ -124,16 +125,16 @@ title Put a re-usable element onto the diagram
 PUMLAPutElement(simpleElement)
 
 note as n1
-The re-usable element "simpleElement"
-is put onto the diagram.
-
-Via the global variables, showing the
-description of the element as well as
-the interfaces is turned off.
-
-So you have a different, more restrained
-view on the element on this diagram.
-end note
+    The re-usable element "simpleElement"
+    is put onto the diagram.
+    
+    Via the global variables, showing the
+    description of the element as well as
+    the interfaces is turned off.
+    
+    So you have a different, more restrained
+    view on the element on this diagram.
+    end note
 @enduml
 ```
 This works out of the box, as everything the diagram needs is already
@@ -152,6 +153,7 @@ For more examples showing off the functionality and magic of `pumla` please...
 [follow this link to more examples](./Examples.md)
 
 ### Installation
+#### Install latest development
 To get the latest developments, clone this git repo to a place somewhere on your Mac/Raspberry Pi or other Unix-like
 system:
 
@@ -161,6 +163,19 @@ system:
 
 After that you should be able to call `pumla <cmd>` at any place, e.g. `pumla init` or `pumla update`. 
 
+#### Install an official release
+The following instructions work only for release equal to or newer than 0.8.3. For installation of
+older releases, please read the installation instructions in the README.md of the
+downloaded archive.
+
+To get a release, do the following: 
+
+- go to the Release page, choose a release version and download the
+corresponding Source Code archive (.zip or .tar.gz).
+- extract the archive
+- change to the unpacked pumla folder, e.g. `cd pumla-0.8.3`
+- install pumla with: `pip install .`
+
 ### Working with the examples
 In order to play around with the examples, you need to initialise the examples repository
   to work on your system. To do that, take the following steps starting in the pumla
@@ -205,7 +220,7 @@ you have fast previews of the `.puml` and markdown files.
   file paths handling in a way that it works across Windows
   and Unix platform, as I also do not have a Windows test platform 
   at hand anymore. It is proven to run on my Macbook (Mojave)
-  with Python 3.8.2 and Raspberry Pi 3 with Python 3.7.3.
+  with Python 3.8.2 and Raspberry Pi 3 with Python 3.7.3 and pip3.
 - tested with PlantUML library v1.2021.7 (via the PyCharm Plugin 
   "PlantUML integration" version 5.5.1)
 

diff --git a/pumla_internal.puml b/pumla_internal.puml
@@ -273,7 +273,7 @@ PUMLAErrorCheck("0", $elemalias, "Could not create instance of element with alia
 ' can be overwritten or turned off with the
 ' global variable.
 !if ($PUMVarShowPUMLAFooterNote)
-center footer created with help of **pumla**: https://github.com/DrMarkusVoss/pumla
+center footer created with help of **pumla** $PUMLAVersionNumber: https://github.com/DrMarkusVoss/pumla
 !endif
 
 

diff --git a/pumla_macros_global.puml b/pumla_macros_global.puml
@@ -1,3 +1,5 @@
+!$PUMLAVersionNumber = "v0.8.3"
+
 !include pumla_global_cfg.puml
 !include pumla_internal.puml
 

diff --git a/setup.cfg b/setup.cfg
@@ -1,6 +1,6 @@
 [metadata]
 name = pumla
-version = 0.8.0
+version = 0.8.3
 description = Command Line Tool for the PlantUML extension to enable architecture element re-usability.
 long_description = file: README.md
 license = GPL-3.0-only

diff --git a/src/pumla/control/cmd_utils.py b/src/pumla/control/cmd_utils.py
@@ -32,10 +32,15 @@ def createPumlaMacrosFile(mainpath):
     pm_comment = pm_comment + "' IN THE FOLDER OF THIS FILE HERE!\n"
     pm_include_macros = "!include " + mainpath + "pumla_macros_global.puml\n"
     pm_include_tv = "!include " + mainpath + "pumla_tagged_values.puml\n"
+    pm_include_project_cfg = '\n!if %file_exists("' + curpath + '/pumla_project_config.puml")\n'
+    pm_include_project_cfg = pm_include_project_cfg +  "!include pumla_project_config.puml\n"
+    pm_include_project_cfg = pm_include_project_cfg + "!endif\n"
+
     with open(pumla_macros_fn, "w") as fil:
         fil.write(pm_comment)
         fil.write(pm_include_macros)
         fil.write(pm_include_tv)
+        fil.write(pm_include_project_cfg)
     fil.close()
 
 

diff --git a/src/pumla/main.py b/src/pumla/main.py
@@ -11,7 +11,7 @@
 __author__ = "Dr. Markus Voss (private person)"
 __copyright__ = "(C) Copyright 2021 by Dr. Markus Voss (private person)"
 __license__ = "GPL"
-__version__ = "0.8.2"
+__version__ = "0.8.3"
 __maintainer__ = "Dr. Markus Voss (private person)"
 __status__ = "Development"
 

diff --git a/test/examples/displayTemp/displayTemp.puml b/test/examples/displayTemp/displayTemp.puml
@@ -8,12 +8,10 @@ PUMLAReUsableAsset("displayTemp", displayTemp, component, "<<block>>") {
 
     PUMLARUAPutTaggedValues()
 
-    !if ($PUMVarShowBodyInternals)
     PUMLARUAInternals() {
         component display
         component conversion
     }
-    !endif
 }
 
 
@@ -33,5 +31,5 @@ note bottom of displayTemp
     only one value is given as input.
 end note
 !endif
-
+PUMLAReUsableAssetFinalize()
 @enduml
diff --git a/test/examples/playground.puml b/test/examples/playground.puml
@@ -1,19 +1,27 @@
 @startuml
-!include modelrepo_json.puml
-!include pumla_macros.puml
-!$PUMVarShowDescr = %false()
-!$PUMVarShowTaggedValues = %true()
-!$PUMVarShowInstantiationRel = %true()
+!include <c4/C4_Container.puml>
+AddElementTag("v1.0", $borderColor="#d73027")
+AddElementTag("v1.1", $fontColor="#d73027")
+AddElementTag("backup", $fontColor="orange")
 
-title nice diagram
+'AddRelTag("backup", $textColor="orange", $lineColor="orange", $lineStyle = DashedLine())
 
-'PUMLASetElementFilterInTagValue("Vendor", "C Ltd.")
+Person(user, "Customer", "People that need products")
+Person(admin, "Administrator", "People that administrates the products via the new v1.1 components", $tags="v1.1")
+Container(spa, "SPA", "angular", "The main interface that the customer interacts with via v1.0", $tags="v1.0")
+Container(spaAdmin, "Admin SPA", "angular", "The administrator interface that the customer interacts with via new v1.1", $tags="v1.1")
+Container(api, "API", "java", "Handles all business logic (incl. new v1.1 extensions)", $tags="v1.0+v1.1")
+ContainerDb(db, "Database", "Microsoft SQL", "Holds product, order and invoice information")
+Container(archive, "Archive", "Audit logging", "Stores 5 years", $tags="backup")
 
-'PUMLAPutAllElementsWithTagValue("Vendor", "C Ltd.")
-
-'PUMLAPutAllElementsWithTagValue("Vendor", "B Inc.")
-
-PUMLAPutAllElements()
+Rel(user, spa, "Uses", "https")
+Rel(spa, api, "Uses", "https")
+Rel_R(api, db, "Reads/Writes")
+Rel(admin, spaAdmin, "Uses", "https")
+Rel(spaAdmin, api, "Uses", "https")
+Rel_L(api, archive, "Writes", "messages", $tags="backup")
 
+user .. spa : huhu
 
+SHOW_LEGEND()
 @enduml
diff --git a/test/examples/tempConv/tempConverter.puml b/test/examples/tempConv/tempConverter.puml
@@ -8,12 +8,10 @@ PUMLAReUsableAsset("Temp. Converter", tempConverter, component, "<<block>>") {
 
     PUMLARUAPutTaggedValues()
 
-    !if ($PUMVarShowBodyInternals)
     PUMLARUAInternals() {
         component conversionModule
         component formulaLib
     }
-    !endif
 }
 
 

diff --git a/test/examples/tempSensorA/tempSensorA.puml b/test/examples/tempSensorA/tempSensorA.puml
@@ -7,7 +7,6 @@
 PUMLAReUsableAsset("Temperature Sensor A", tempSensorA, component, "<<block>>") {
     PUMLARUAPutTaggedValues()
 
-    !if ($PUMVarShowBodyInternals)
     PUMLARUAInternals() {
 
         component getSignal
@@ -16,7 +15,6 @@ PUMLAReUsableAsset("Temperature Sensor A", tempSensorA, component, "<<block>>")
 
         PUMLAPutInternalDynElement(internalSequence)
     }
-    !endif
 }
 
 PUMLARUAAddTaggedValue("Vendor", "A GmbH")

diff --git a/test/examples/tempSys.puml b/test/examples/tempSys.puml
@@ -1,6 +1,7 @@
 'PUMLAMR
 @startuml
 !include pumla_macros.puml
+!include modelrepo_json.puml
 
 PUMLAReUsableAsset("Temperature System", tempSys, node, "<<block>>") {
 
@@ -11,6 +12,7 @@ PUMLAReUsableAsset("Temperature System", tempSys, node, "<<block>>") {
             PUMLAInjectChildElements(tempSys)
         }
         !endif
+
 }
 
 PUMLARUAAddTaggedValue("Vendor", "C Ltd.")

diff --git a/test/examples/thisShallBeIgnored/c4tests/modelrepo_json.puml b/test/examples/thisShallBeIgnored/c4tests/modelrepo_json.puml
@@ -0,0 +1,6 @@
+!$allelems = {"modelrepopath": "/Users/mvoss/Desktop/git/github/pumla/test/examples/thisShallBeIgnored/c4tests", "modelrepofile": "./modelrepo_json.puml", "elements": []}
+
+!$allrelations = {"modelrelationrepopath": "/Users/mvoss/Desktop/git/github/pumla/test/examples/thisShallBeIgnored/c4tests", "modelrelationrepofile": "./modelrepo_json.puml", "relations": [{"id": "REL#publicStateToIF", "start": "'(publicState", "end": "temp_dF_tempSensorB", "reltype": "..>", "reltxt": "provides", "path": "./", "filename": "simplePerson.puml"}]}
+
+!$allconnections = {"modelconnectionrepopath": "/Users/mvoss/Desktop/git/github/pumla/test/examples/thisShallBeIgnored/c4tests", "modelconnectionrepofile": "./modelrepo_json.puml", "connections": []}
+
diff --git a/test/examples/thisShallBeIgnored/c4tests/pumla_macros.puml b/test/examples/thisShallBeIgnored/c4tests/pumla_macros.puml
@@ -0,0 +1,10 @@
+' THIS IS AN AUTOMATICALLY GENERATED FILE BY pumla init 
+' DO NOT CHANGE MANUALLY!
+' TO ADOPT THE PATHS TO YOUR SYSTEM, CALL pumla init AGAIN
+' IN THE FOLDER OF THIS FILE HERE!
+!include /Users/mvoss/Desktop/git/github/pumla/pumla_macros_global.puml
+!include /Users/mvoss/Desktop/git/github/pumla/pumla_tagged_values.puml
+
+!if %file_exists("/Users/mvoss/Desktop/git/github/pumla/test/examples/thisShallBeIgnored/c4tests/pumla_project_config.puml")
+!include pumla_project_config.puml
+!endif
diff --git a/test/examples/thisShallBeIgnored/c4tests/simpleC4diagram.puml b/test/examples/thisShallBeIgnored/c4tests/simpleC4diagram.puml
@@ -0,0 +1,19 @@
+@startuml
+!include pumla_macros.puml
+!include modelrepo_json.puml
+
+
+!$PUMVarShowDescr = %false()
+!$PUMVarShowInterfaces = %false()
+!$PUMVarShowBodyInternals = %true()
+!$PUMVarShowTaggedValues = %true()
+
+title Put a re-usable element onto the diagram
+
+' put the "simpleElement" from the model repository
+' onto the diagram
+'PUMLAPutElement(simplePerson)
+!include simplePerson.puml
+
+
+@enduml
diff --git a/test/examples/thisShallBeIgnored/c4tests/simplePerson.puml b/test/examples/thisShallBeIgnored/c4tests/simplePerson.puml
@@ -0,0 +1,23 @@
+'PUMLAMR
+@startuml
+!include pumla_macros.puml
+!include modelrepo_json.puml
+!include <c4/C4_Container>
+
+Person(simplePerson, "Simple Person", "People that need products") {
+    PUMLAPutTaggedValues(simplePerson)
+
+    !if ($PUMVarShowBodyInternals)
+        component "internal elements"
+    !endif
+}
+
+PUMLAAddTaggedValue(simplePerson, "Age", "30-49")
+
+!if ($PUMVarShowDescr)
+note bottom of simplePerson
+    A person defined as C4 model actor.
+end note
+!endif
+%version()
+@enduml
diff --git a/test/examples/thisShallBeIgnored/simple/pumla_macros.puml b/test/examples/thisShallBeIgnored/simple/pumla_macros.puml
@@ -4,3 +4,7 @@
 ' IN THE FOLDER OF THIS FILE HERE!
 !include /Users/mvoss/Desktop/git/github/pumla/pumla_macros_global.puml
 !include /Users/mvoss/Desktop/git/github/pumla/pumla_tagged_values.puml
+
+!if %file_exists("/Users/mvoss/Desktop/git/github/pumla/test/examples/thisShallBeIgnored/simple/pumla_project_config.puml")
+!include pumla_project_config.puml
+!endif
diff --git a/test/examples/thisShallBeIgnored/simple/pumla_project_config.puml b/test/examples/thisShallBeIgnored/simple/pumla_project_config.puml
@@ -0,0 +1,20 @@
+ 'modify this to how you like it.
+
+' turn on (true) or off (false) the default
+' pumla advertising footer. Can also be
+' overwritten in each diagram with own
+' footer.
+!$PUMVarShowPUMLAFooterNote = %true()
+
+' turn on (true) or off (false) the
+' Error Note generation. With error
+' notes you get information about a
+' failed pumla command in a red note
+' on the diagram.
+!$PUMVarShowPUMLAErrorNotes = %true()
+
+' choose the color of the tagged values
+' table. Color names have to be written
+' in small letters.
+!$PUMColorTaggedValues = orange
+
diff --git a/test/examples/thisShallBeIgnored/simple/simpleDiagram.puml b/test/examples/thisShallBeIgnored/simple/simpleDiagram.puml
@@ -4,7 +4,7 @@
 
 !$PUMVarShowDescr = %false()
 !$PUMVarShowInterfaces = %false()
-!$PUMVarShowBodyInternals = %false()
+!$PUMVarShowBodyInternals = %true()
 !$PUMVarShowTaggedValues = %true()
 
 title Put a re-usable element onto the diagram
@@ -14,14 +14,14 @@ title Put a re-usable element onto the diagram
 PUMLAPutElement(simpleElement)
 
 note as n1
-The re-usable element "simpleElement"
-is put onto the diagram.
+    The re-usable element "simpleElement"
+    is put onto the diagram.
 
-Via the global variables, showing the
-description of the element as well as
-the interfaces is turned off.
+    Via the global variables, showing the
+    description of the element as well as
+    the interfaces is turned off.
 
-So you have a different, more restrained
-view on the element on this diagram.
+    So you have a different, more restrained
+    view on the element on this diagram.
 end note
 @enduml
diff --git a/test/examples/wirelessUnit/wirelessUnit.puml b/test/examples/wirelessUnit/wirelessUnit.puml
@@ -7,12 +7,10 @@ PUMLAReUsableAsset("Wireless Unit", wirelessUnit, rectangle, "<<block>> <<extern
 
     PUMLARUAPutTaggedValues()
 
-    !if ($PUMVarShowBodyInternals)
     PUMLARUAInternals() {
         component transmitter
         component receiver
     }
-    !endif
 }
 
 PUMLARUAAddTaggedValue("Vendor", "XY")