From 2a69cab87cb257de9c3a346baaf1d23cddb4d8c7 Mon Sep 17 00:00:00 2001 From: "Dr. Markus Voss" Date: Thu, 23 Sep 2021 21:52:14 +0200 Subject: [PATCH] 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. --- README.md | 45 ++++++++++++------- pumla_internal.puml | 2 +- pumla_macros_global.puml | 2 + setup.cfg | 2 +- src/pumla/control/cmd_utils.py | 5 +++ src/pumla/main.py | 2 +- test/examples/displayTemp/displayTemp.puml | 4 +- test/examples/playground.puml | 32 ++++++++----- test/examples/tempConv/tempConverter.puml | 2 - test/examples/tempSensorA/tempSensorA.puml | 2 - test/examples/tempSys.puml | 2 + .../c4tests/modelrepo_json.puml | 6 +++ .../c4tests/pumla_macros.puml | 10 +++++ .../c4tests/simpleC4diagram.puml | 19 ++++++++ .../c4tests/simplePerson.puml | 23 ++++++++++ .../simple/pumla_macros.puml | 4 ++ .../simple/pumla_project_config.puml | 20 +++++++++ .../simple/simpleDiagram.puml | 16 +++---- test/examples/wirelessUnit/wirelessUnit.puml | 2 - 19 files changed, 153 insertions(+), 47 deletions(-) create mode 100644 test/examples/thisShallBeIgnored/c4tests/modelrepo_json.puml create mode 100644 test/examples/thisShallBeIgnored/c4tests/pumla_macros.puml create mode 100644 test/examples/thisShallBeIgnored/c4tests/simpleC4diagram.puml create mode 100644 test/examples/thisShallBeIgnored/c4tests/simplePerson.puml create mode 100644 test/examples/thisShallBeIgnored/simple/pumla_project_config.puml diff --git a/README.md b/README.md index 34e14c6..e0c543c 100644 --- 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 ` 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 index ac394fc..3ca1efc 100644 --- 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 index ae1ea29..a19f60d 100644 --- 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 index e1ab454..1787fbd 100644 --- 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 index 5dd9884..1106753 100644 --- 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 index 5f01d12..276c6dc 100644 --- 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 index 5075f00..5b85069 100644 --- a/test/examples/displayTemp/displayTemp.puml +++ b/test/examples/displayTemp/displayTemp.puml @@ -8,12 +8,10 @@ PUMLAReUsableAsset("displayTemp", displayTemp, component, "<>") { 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 \ No newline at end of file diff --git a/test/examples/playground.puml b/test/examples/playground.puml index 0d8d318..c4855c7 100644 --- 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 +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 index 697f3c2..5af3617 100644 --- a/test/examples/tempConv/tempConverter.puml +++ b/test/examples/tempConv/tempConverter.puml @@ -8,12 +8,10 @@ PUMLAReUsableAsset("Temp. Converter", tempConverter, component, "<>") { PUMLARUAPutTaggedValues() - !if ($PUMVarShowBodyInternals) PUMLARUAInternals() { component conversionModule component formulaLib } - !endif } diff --git a/test/examples/tempSensorA/tempSensorA.puml b/test/examples/tempSensorA/tempSensorA.puml index 20e4acb..93c151a 100644 --- a/test/examples/tempSensorA/tempSensorA.puml +++ b/test/examples/tempSensorA/tempSensorA.puml @@ -7,7 +7,6 @@ PUMLAReUsableAsset("Temperature Sensor A", tempSensorA, component, "<>") { PUMLARUAPutTaggedValues() - !if ($PUMVarShowBodyInternals) PUMLARUAInternals() { component getSignal @@ -16,7 +15,6 @@ PUMLAReUsableAsset("Temperature Sensor A", tempSensorA, component, "<>") PUMLAPutInternalDynElement(internalSequence) } - !endif } PUMLARUAAddTaggedValue("Vendor", "A GmbH") diff --git a/test/examples/tempSys.puml b/test/examples/tempSys.puml index c282995..3e0e4b3 100644 --- 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, "<>") { @@ -11,6 +12,7 @@ PUMLAReUsableAsset("Temperature System", tempSys, node, "<>") { 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 new file mode 100644 index 0000000..68b46da --- /dev/null +++ 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 new file mode 100644 index 0000000..f1f3f62 --- /dev/null +++ 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 new file mode 100644 index 0000000..cdad8de --- /dev/null +++ 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 new file mode 100644 index 0000000..8009ce1 --- /dev/null +++ b/test/examples/thisShallBeIgnored/c4tests/simplePerson.puml @@ -0,0 +1,23 @@ +'PUMLAMR +@startuml +!include pumla_macros.puml +!include modelrepo_json.puml +!include + +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 \ No newline at end of file diff --git a/test/examples/thisShallBeIgnored/simple/pumla_macros.puml b/test/examples/thisShallBeIgnored/simple/pumla_macros.puml index 632923b..bab0a3f 100644 --- 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 new file mode 100644 index 0000000..5914c6f --- /dev/null +++ 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 index 6569f3f..6b619ae 100644 --- 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 index addd20c..1095e5b 100644 --- a/test/examples/wirelessUnit/wirelessUnit.puml +++ b/test/examples/wirelessUnit/wirelessUnit.puml @@ -7,12 +7,10 @@ PUMLAReUsableAsset("Wireless Unit", wirelessUnit, rectangle, "<> <