Improvements

Author: bitsmuggler

.gitignore

@@ -9,4 +9,5 @@ documentation/images/diag-*.png
 .idea/
 .gradle/
 build/
-documentation/adrs/*.adoc
+documentation/adrs/*.adoc
+c4-language-server.log

README.adoc

@@ -9,7 +9,9 @@ It shows how to use the techniques described in https://www.workingsoftware.dev/
 
 Check out the deployed https://bitsmuggler.github.io/arc42-c4-software-architecture-documentation-example/[HTML build] provided on GitHub Pages.
 
-Technologies involved:
+:toc: 
+
+== Technologies
 
 * https://arc42.org/[arc42] to get the structure for the software architecture documentation
 * https://c4model.com/[C4 Model] an "abstraction-first" approach to diagramming software architecture, based upon abstractions that reflect how software architects and developers think about and build software.
@@ -22,43 +24,12 @@ Technologies involved:
 
 For more tech inspiration take a look at the https://www.workingsoftware.dev/documentation-as-code-tools[Documentation as Code Technology Radar]
 
-== Prerequisites
-
-=== Generate PlantUML Diagrams from the C4 Model
-
-==== With the Structurizr CLI via Docker Image
-
-[source, bash]
-----
-docker run -it --rm -v $PWD:/usr/local/structurizr structurizr/cli export -w documentation/bank.dsl -format plantuml/structurizr -output documentation/diagrams
-----
-
-==== With a local installed Structurizr CLI
-
-Download the https://github.com/structurizr/cli/releases[structurizr-cli], unzip and move it into `./bin/structurizr-cli` or use the latest Docker Image
-
-[source, bash]
-----
-curl --show-error --location https://github.com/structurizr/cli/releases/download/v{selected-version}/structurizr-cli-{selected-version}.zip  -o tmp.zip && unzip -d bin/structurizr-cli/. tmp.zip && rm tmp.zip
-----
-
-Generate the diagrams from the structurizr workspace model
-
-[source, bash]
-----
-./bin/structurizr-cli/structurizr.sh export -w documentation/bank.dsl -format plantuml/structurizr -output documentation/diagrams
-----
-
-==== With the docToolchain
 
-https://doctoolchain.org/docToolchain/[docToolchain] uses the Structurizr CLI to generate the PlantUML diagrams from the C4 Model described in the Structurizr DSL.
+== Prerequisites
 
-[source, bash]
-----
-./dtcw exportStructurizr
-----
+=== Migrate markdown based ADRs from adr-tools to AsciiDoc
 
-== Migrate markdown based ADRs from adr-tools to AsciiDoc
+Unfortunately, the adr-tools do not support AsciiDoc as a format for the ADRs. Therefore, you have to migrate the existing markdown based ADRs to AsciiDoc.
 
 === Install and configure adr-tools
 
@@ -102,7 +73,18 @@ What becomes easier or more difficult to do and any risks introduced by the chan
 ./dtcw exportMarkdown && cp ./build/adrs/*.adoc ./documentation/adrs/
 ----
 
-== Generate the software architecture documentation representations
+== Build the software architecture documentation
+
+=== Generate PlantUML Diagrams from the C4 Model
+
+https://doctoolchain.org/docToolchain/[docToolchain] uses the Structurizr CLI to generate the PlantUML diagrams from the C4 Model described in the Structurizr DSL.
+
+[source, bash]
+----
+./dtcw exportStructurizr
+----
+
+=== Generate the software architecture documentation representations
 
 NOTE: these examples use the public https://kroki.io[kroki.io] instance to generate the diagrams.
 For your own documentation, replace the references to kroki.io with your own kroki instance.
@@ -126,4 +108,33 @@ Generate the documentation as Microsite
 [source, bash]
 ----
 ./dtcw generateSite
+----
+
+=== Appendix
+
+If you want to build everything without the `./dtcw` script, you can use the following commands.
+
+==== Generate the PlantUML diagrams from the Structurizr DSL
+
+*With the Structurizr CLI via Docker Image*
+
+[source, bash]
+----
+docker run -it --rm -v $PWD:/usr/local/structurizr structurizr/cli export -w documentation/bank.dsl -format plantuml/structurizr -output documentation/diagrams
+----
+
+*With a local installed Structurizr CLI*
+
+* Download the https://github.com/structurizr/cli/releases[structurizr-cli], unzip and move it into `./bin/structurizr-cli` or use the latest Docker Image
+
+[source, bash]
+----
+curl --show-error --location https://github.com/structurizr/cli/releases/download/{selected-version}/structurizr-cli.zip  -o tmp.zip && mkdir -p bin/structurizr-cli && unzip -d bin/structurizr-cli tmp.zip && rm tmp.zip
+----
+
+* Generate the diagrams from the structurizr workspace model
+
+[source, bash]
+----
+./bin/structurizr-cli/structurizr.sh export -w documentation/bank.dsl -format plantuml/structurizr -output documentation/diagrams
 ----

documentation/arc42/03_context_and_scope.adoc

@@ -4,10 +4,6 @@
 [[section-system-scope-and-context]]
 == System Scope and Context
 
-
-
-
-
 === Business Context
 
 [plantuml, format=png]   

documentation/arc42/05_building_block_view.adoc

@@ -11,7 +11,6 @@
 [plantuml, format=png]   
 ....
 include::../diagrams/Containers.puml[]
-include::../diagrams/Containers-key.puml[]
 ....
 
 **Legende**
@@ -82,13 +81,13 @@ _<black box template>_
 
 [plantuml, format=png]   
 ....
-include::../diagrams/Components.puml[]
+include::../diagrams/structurizr-Components.puml[]
 ....
 
 **Legende**
 [plantuml, format=png]   
 ....
-include::../diagrams/Components-key.puml[]
+include::../diagrams/structurizr-Components-key.puml[]
 ....
 
 

documentation/arc42/06_runtime_view.adoc

@@ -4,9 +4,6 @@
 [[section-runtime-view]]
 == Runtime View
 
-
-
-
 === Sign-In
 
 [plantuml, format=png]   
@@ -25,8 +22,4 @@ include::../diagrams/SignIn-key.puml[]
 * _<insert description of the notable aspects of the interactions between the
 building block instances depicted in this diagram.>_
 
-=== <Runtime Scenario 2>
-
-=== ...
-
-=== <Runtime Scenario n>
+=== <Runtime Scenario n>

dtcw

@@ -14,6 +14,9 @@ set -o pipefail
 # Set DTC_VERSION to "latest" to get the latest, yet unreleased version.
 : "${DTC_VERSION:=3.4.1}"
 
+# if not set, public docker hub is used
+: "${DTC_DOCKER_PREFIX:=}"
+
 # The 'generateSite' and 'copyThemes' tasks support DTC_SITETHEME, an URL of a theme.
 # export DTC_SITETHEME=https://....zip
 
@@ -22,7 +25,7 @@ set -o pipefail
 # export DTC_TEMPLATE1=https://....zip
 # export DTC_TEMPLATE2=https://....zip
 
-# docToolchain configurtion file may be overruled by the user
+# docToolchain configuration file may be overruled by the user
 : "${DTC_CONFIG_FILE:=docToolchainConfig.groovy}"
 
 # Contains the current project git branch, "-" if not available
@@ -82,7 +85,7 @@ main() {
         install_component_and_exit "${environment}" "${2-}"
     elif [ "${1}" = "getJava" ]; then
         # TODO: remove getJava in the next major release
-        echo "Warning: 'getJava' is deprecated and and will be removed. Use './dtcw install java' instead."
+        echo "Warning: 'getJava' is deprecated and will be removed. Use './dtcw install java' instead."
         install_component_and_exit "${environment}" "java"
     fi
 
@@ -126,7 +129,9 @@ main() {
     fi
 
     # echo "Command to invoke: ${command}"
-    exec ${emu} ${bash} -c "${command}"
+    # shellcheck disable=SC2086
+    # as we hope to know what we are doing here ;-)
+    exec ${emu} ${bash} ${DTC_SHELL_DEBUG:-} -c "${command}"
 }
 
 assert_argument_exists() {
@@ -219,6 +224,11 @@ get_dtc_installations() {
 
     if [ -x "${DTC_HOME}/bin/doctoolchain" ]; then
         installations+=" local"
+    else
+        # maybe it is just available in the path
+        if command -v doctoolchain >/dev/null 2>&1; then
+            installations+=" local"
+        fi
     fi
 
     if [[ "${envs}" =~ sdk ]] && sdk_home_doctoolchain "${version}" &> /dev/null ; then
@@ -624,7 +634,7 @@ build_command() {
         docker_args="run --rm -i --platform linux/amd64 -u $(id -u):$(id -g) --name ${container_name} \
             -e DTC_HEADLESS=true -e DTC_SITETHEME -e DTC_PROJECT_BRANCH=${DTC_PROJECT_BRANCH} \
             ${docker_extra_arguments} ${env_file_option} \
-            --entrypoint /bin/bash -v '${pwd}:/project' ${docker_image}:v${version}"
+            --entrypoint /bin/bash -v '${pwd}:/project' ${DTC_DOCKER_PREFIX}${docker_image}:v${version}"
 
         cmd="docker ${docker_args} -c \"doctoolchain . ${*} ${DTC_OPTS} && exit\""
     else
@@ -634,7 +644,16 @@ build_command() {
             DTC_OPTS="${DTC_OPTS} '-Dgradle.user.home=${DTC_ROOT}/.gradle'"
         fi
         if [ "${env}" = local ]; then
-            cmd="${DTC_HOME}/bin/doctoolchain . ${*} ${DTC_OPTS}"
+            if [ -x "${DTC_HOME}/bin/doctoolchain" ]; then
+                cmd="${DTC_HOME}/bin/doctoolchain"
+            # is doctoolchain available on the path?
+            elif command -v doctoolchain >/dev/null 2>&1; then
+                cmd="doctoolchain"
+            else
+                echo "Could not find doctoolchain executable, neither in '${DTC_HOME}' nor on PATH ('${PATH}')" >&2
+                exit 1
+            fi
+            cmd="${cmd} . ${*} ${DTC_OPTS}"
         else
             cmd="$(sdk_home_doctoolchain "${version}")/bin/doctoolchain . ${*} ${DTC_OPTS}"
         fi