Added Helper documentation.

Author: pme123

00-docs/src/docs/company/00-docs.md

@@ -25,4 +25,5 @@ The following files will be created by `.helper.scala prepareDocs`:
     | - overviewDependencies.md
     | - release.md
 ```
-So do **not adjust** them manually.
+So do **not adjust** them manually.
+

00-docs/src/docs/company/04-helper.md

@@ -1,21 +1,113 @@
 # 04-helper
 
-### CompanyDevHelper
-With the `CompanyDevHelper` you can customize  _Camundala_ for your Company:
-
-```scala mdoc
-import camundala.api.*
-import camundala.helper.dev.DevHelper
-import camundala.helper.util.*
+## CompanyDevHelper
+With the `CompanyDevHelper` you can customize  the development process for each project.
 
+```scala 
 case class CompanyDevHelper(projectName: String, subProjects: Seq[String] = Seq.empty)
-    extends DevHelper:
+  extends DevHelper:
+
+  lazy val apiConfig: ApiConfig = CompanyApiCreator.apiConfig
+  lazy val devConfig: DevConfig = CompanyDevConfig.config(projectName, subProjects)
+
+end CompanyDevHelper
+```
+### ApiConfig
+Taken from `CompanyApiCreator.apiConfig`, see [CompanyApiCreator]
+
+### DevConfig
+Taken from `CompanyApiCreator.apiConfig`, see [CompanyDevConfig]
 
-  lazy val apiConfig: ApiConfig = ApiConfig("mycompany")//.withTenantId("mycompany")...
+## CompanyDevConfig
+The `CompanyDevConfig` is a helper to create the `DevConfig` for the `CompanyDevHelper`.
+
+```scala
+object CompanyDevConfig:
+  def config(
+      projectName: String,
+      subProjects: Seq[String] = Seq.empty
+  ) = DevConfig(
+    projectName,
+    subProjects,
+    camundala.api.defaultProjectConfigPath
+  ).withVersionConfig(companyVersionConfig)
+   // .withSbtConfig(SbtConfig(...))
+   // .withPublishConfig(PublishConfig(...))
+   // .withPostmanConfig(PostmanConfig(...))
+   // .withDockerConfig(DockerConfig(...))
+
+  private lazy val companyVersionConfig = VersionConfig(
+    scalaVersion = BuildInfo.scalaVersion,
+    camundalaVersion = BuildInfo.camundalaV,
+    companyCamundalaVersion = BuildInfo.version,
+    sbtVersion = BuildInfo.sbtVersion,
+    otherVersions = Map()
+  )
+end CompanyDevConfig
+```
+Here the default values for `DevConfig`:
+```scala
+case class DevConfig(
+    // project configuration taken from the PROJECT.conf
+    apiProjectConf: ApiProjectConf,
+    // subProjects to optimize compilation time - use only for big projects
+    subProjects: Seq[String] = Seq.empty,
+    // additional sbt configuration for sbt generation
+    sbtConfig: SbtConfig = SbtConfig(),
+    // versions used for generators
+    versionConfig: VersionConfig = VersionConfig(),
+    // If you have a Postman account, add the config here (used for ./helper.scala deploy..)
+    postmanConfig: Option[PostmanConfig] = None,
+    // Adjust the DockerConfig (used for ./helper.scala deploy../ docker..)
+    dockerConfig: DockerConfig = DockerConfig(),
+    // If you have a webdav server to publish the docs, add the config here (used in ./helper.scala publish..)
+    publishConfig: Option[PublishConfig] = None,
+    // general project structure -  do not change if possible
+    modules: Seq[ModuleConfig] = DevConfig.modules
+)
+```
+### defaultProjectConfigPath
 
-  lazy val deployConfig: Option[DeployConfig] = ???
-  lazy val devConfig: DevConfig = ???
-  lazy val dockerConfig: DockerConfig = ???
-  lazy val publishConfig: Option[PublishConfig] = ???
+At the moment we use a configuration file for each project. **This may change in the future.**
+The default path is `projectBasePath / PROJECT.conf` and is generated by `./helper.scala update` in the project.
 
+Example:
+```scala
+org = "mycompany"
+name = "mycompany-accounting"
+version = "1.25.0-SNAPSHOT"
+dependencies: {
+  "mycompany-helper": "mycompany:mycompany-helper:1.4.*"
+  "mycompany-services": "mycompany:mycompany-services:1.7.*"
+  "mycompany-crm": "mycompany:mycompany-crm:2.28.*"
+}
 ```
+
+## CompanyCamundalaDevHelper
+The `CompanyCamundalaDevHelper` is a helper dedicated for the `company-camundala` project.
+
+See [Development]
+
+```scala
+object CompanyCamundalaDevHelper
+    extends DevCompanyCamundalaHelper:
+
+  lazy val apiConfig: ApiConfig = CompanyApiCreator.apiConfig
+    .copy(
+      basePath = os.pwd /"00-docs",
+      tempGitDir = os.pwd / os.up / "git-temp"
+    )
+
+  lazy val devConfig: DevConfig = CompanyDevConfig.config(BuildInfo.name, Seq.empty)
+  
+end CompanyCamundalaDevHelper
+```
+
+### apiConfig
+The `apiConfig` is taken from `CompanyApiCreator.apiConfig` and can be customized.
+The `basePath` and the `tempGitDir` must be adjusted, as `company-camundala` 
+has a different file structure, compared to a project.
+
+### devConfig
+Here your `DevConfig` defined in the `CompanyDevConfig.config` method, should work. 
+The only adjustments are the `projectName` and that no `subProjects` are needed.

00-docs/src/docs/development/projectDev.md

@@ -1,5 +1,4 @@
 # Project Development
-**Experimental**
 
 The following chapters describe the tasks to support the project development.
 
@@ -11,6 +10,33 @@ And then you can type `./helper.scala <command>` to get help for a specific comm
 
 The `version` is optional and defaults to `1`.
 
+## helper.scala
+This file will be replaced with `./helper.scala update`. However, you need to set there the 
+subprojects you want to use.
+
+```scala
+#!/usr/bin/env -S scala shebang
+// DO NOT ADJUST. This file is replaced by `./helper.scala update`.
+//> using dep mycompany::mycompany-camundala-helper:0.1.0-SNAPSHOT
+
+import mycompany.camundala.helper.*
+
+lazy val projectName: String = "mycompany-myProject"
+lazy val subProjects = Seq(
+  "accounting",
+  "hr"
+)
+
+@main
+def run(command: String, arguments: String*): Unit =
+  CompanyDevHelper(projectName, subProjects).run(command, arguments*)
+```
+### subProjects
+Compile time can be optimized by using subprojects - this makes the project a bit more complex, 
+as for each subProject, a SBT module is created.
+
+`./helper.scala update` will generate this file but preserve the project name and subprojects.
+
 ## update
 Whenever you have changes in the `company-camundala` project or in one of your dependencies, 
 you can update the project with the following command:
@@ -31,7 +57,8 @@ You will get a warning, but the file will not be replaced.
 Creates a new Release for the BPMN project and publishes to the repository(e.g. Artifactory)
 
 @:callout(info)
-Adjust the `CompanyDevHelper.publishConfig` configuration.
+If you want to provide the documentation on a WebDAV server, 
+you need a `CompanyDevHelper.devConfig.publishConfig` configuration.
 
 @:@
 
@@ -66,7 +93,7 @@ The following steps are executed:
 Deploys the BPMN project to the local Camunda server and runs the Simulation you're working on.
 
 @:callout(info)
-**Be aware** that `CompanyDevHelper.deployConfig` must be defined.
+**Be aware** that `CompanyDevHelper.devConfig.postmanConfig` must be defined.
 
 At the moment, only deployment via _Postman Collection_ is supported (using Camunda REST API to deploy).
 @:@
@@ -265,7 +292,7 @@ To run the Camunda Server locally, you can use `docker-compose`.
 **Precondition**: 
 - You have to have `docker` and `docker-compose` installed.
 - You need to have a `docker-compose.yml` in `dev-company/docker` directory.
-- Adjust the `CompanyDevHelper.dockerConfig` configuration.
+- Adjust the `CompanyDevHelper.devConfig.dockerConfig` configuration.
 
 @:@
 

03-api/src/main/scala/camundala/api/ApiConfig.scala

@@ -92,10 +92,10 @@ object ApiConfig:
 end ApiConfig
 
 case class ProjectsConfig(
-    // Path to your ApiProjectConf - default is os.pwd / PROJECT.conf
-    projectConfPath: os.RelPath = defaultProjectPath,
-    // grouped configs per GitRepos - so it is possible to use projects from different Repos
-    perGitRepoConfigs: Seq[ProjectsPerGitRepoConfig] = Seq.empty
+                           // Path to your ApiProjectConf - default is os.pwd / PROJECT.conf
+                           projectConfPath: os.RelPath = defaultProjectConfigPath,
+                           // grouped configs per GitRepos - so it is possible to use projects from different Repos
+                           perGitRepoConfigs: Seq[ProjectsPerGitRepoConfig] = Seq.empty
 ):
 
   lazy val isConfigured: Boolean = perGitRepoConfigs.nonEmpty

03-api/src/main/scala/camundala/api/exports.scala

@@ -5,7 +5,7 @@ import camundala.bpmn.shortenName
 import camundala.domain.*
 
 val catalogFileName = "catalog.md"
-val defaultProjectPath = os.rel / "PROJECT.conf"
+val defaultProjectConfigPath = os.rel / "PROJECT.conf"
 
 def shortenTag(refIdentShort: String) =
   val tag = shortenName(refIdentShort)

04-helper/src/main/scala/camundala/helper/dev/DevCompanyCamundalaHelper.scala

@@ -1,15 +1,14 @@
 package camundala.helper.dev
 
-import camundala.api.ApiConfig
 import camundala.helper.dev.company.docs.DocCreator
 import camundala.helper.dev.publish.PublishHelper
 import camundala.helper.dev.publish.PublishHelper.*
-import camundala.helper.util.{DevConfig, Helpers, PublishConfig}
+import camundala.helper.util.{DevConfig, PublishConfig}
 
 import scala.util.{Failure, Success, Try}
 
 // dev-company/company-camundala/helper.scala
-trait DevCompanyCamundalaHelper extends Helpers, DocCreator:
+trait DevCompanyCamundalaHelper extends DocCreator:
   def devConfig: DevConfig
 
   def runForCompany(command: String, arguments: String*): Unit =
@@ -24,6 +23,8 @@ trait DevCompanyCamundalaHelper extends Helpers, DocCreator:
     end match
   end runForCompany
 
+  protected def publishConfig: Option[PublishConfig] = devConfig.publishConfig
+
   private def runCommand(command: Command, args: Seq[String]): Unit =
     command match
       case Command.publish if args.size == 1 =>

04-helper/src/main/scala/camundala/helper/dev/DevHelper.scala

@@ -12,12 +12,9 @@ import scala.util.{Failure, Success, Try}
 trait DevHelper:
   def apiConfig: ApiConfig
   def devConfig: DevConfig
-  def publishConfig: Option[PublishConfig]
-  def deployConfig: Option[DeployConfig]
-  def dockerConfig: DockerConfig
+
   given DevConfig = devConfig
   given ApiConfig = apiConfig
-  given Option[PublishConfig] = publishConfig
 
   def run(command: String, arguments: String*): Unit =
     val args = arguments.toSeq
@@ -115,7 +112,7 @@ trait DevHelper:
       case Command.deploy =>
         args match
           case Seq(simulation) =>
-            deployConfig
+            devConfig.postmanConfig
               .map(DeployHelper(_).deploy(Some(simulation)))
               .getOrElse(println("deploy is not supported as there is no deployConfig"))
           case other =>
@@ -124,11 +121,11 @@ trait DevHelper:
             println(s"Example: $command OpenAccountSimulation")
       // docker
       case Command.dockerUp =>
-        DockerHelper(dockerConfig).dockerUp()
+        DockerHelper(devConfig.dockerConfig).dockerUp()
       case Command.dockerStop =>
-        DockerHelper(dockerConfig).dockerStop()
+        DockerHelper(devConfig.dockerConfig).dockerStop()
       case Command.dockerDown =>
-        DockerHelper(dockerConfig).dockerDown()
+        DockerHelper(devConfig.dockerConfig).dockerDown()
 
   private def printBadActivity(command: Command, args: Seq[String]): Unit =
     println(s"Invalid arguments for command $command: $args")