Added initial version of docs..

Author: rcschrg

docs/Project.toml

@@ -0,0 +1,9 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
+Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
+DistributedResourceOptimization = "5e49fdec-d473-4d14-b295-7bff2fcf1925"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[compat]
+Documenter = "~0.27"

docs/make.jl

@@ -0,0 +1,31 @@
+
+using Documenter, DistributedResourceOptimization, Test, Logging
+
+logger = Test.TestLogger(min_level=Info);
+
+with_logger(logger) do
+    makedocs(
+        modules=[DistributedResourceOptimization],
+        format=Documenter.HTML(; assets=["assets/theme_overrides.css"], prettyurls=get(ENV, "CI", nothing) == "true"),
+        authors="Rico Schrage",
+        sitename="DistributedResourceOptimization.jl Documentation",
+        pages=Any["Home"=>"index.md",
+            "Getting Started"=>"getting_started.md",
+            "API"=>"api.md"],
+        repo="https://github.com/Digitalized-Energy-Systems/DistributedResourceOptimization.jl",
+    )
+end
+
+for record in logger.logs
+    @info record.message
+    # Check if @example blocks did not succeed -> fail then
+    if record.level == Warn && occursin("failed to run `@example` block", record.message)
+        throw("Some Documentation example did not work, check the logs and fix the error.")
+    end
+end
+
+deploydocs(
+    repo="github.com/Digitalized-Energy-Systems/DistributedResourceOptimization.jl.git",
+    push_preview=true,
+    devbranch="development"
+)

docs/src/api.md

@@ -0,0 +1,91 @@
+# API
+
+# Express
+
+This part contains basic convenience functions for creating and running Mango.jl simulations. 
+
+```@autodocs
+Modules = [Mango]
+Private = false
+Pages = ["express/api.jl"]
+```
+
+# Agent and Roles
+
+Here, the API for the agent structs created with @agent/@role is listed. 
+
+```@autodocs
+Modules = [Mango]
+Private = false
+Pages = ["agent/api.jl", "agent/core.jl", "agent/role.jl", "agent/services.jl"]
+Order = [:macro, :function, :constant, :type, :module]
+```
+
+# Real time container
+
+This part contains the API related to the container construction, access and management.
+
+```@autodocs
+Modules = [Mango]
+Private = false
+Pages = ["container/api.jl", "container/core.jl", "container/mqtt.jl", "container/protocol.jl", "container/tcp.jl"]
+```
+
+# Simulation
+
+In the following the APIs regarding the simulation world are listed.
+
+```@autodocs
+Modules = [Mango]
+Private = false
+Pages = ["simulation/container.jl", "simulation/communication.jl", "simulation/tasks.jl", "simulation/world.jl"]
+```
+
+# Simulation Environment
+
+In the following the APIs regarding the simulation environment are listed.
+
+```@autodocs
+Modules = [Mango]
+Private = false
+Pages = ["environment/api.jl", "environment/core.jl"]
+```
+
+# Scheduling
+
+In the following the APIs for scheduling TaskData is listed.
+
+```@autodocs
+Modules = [Mango]
+Private = false
+Pages = ["util/scheduling.jl"]
+```
+
+# Topology
+
+In the following the APIs for creating, aplying and using topologies is listed.
+
+```@autodocs
+Modules = [Mango]
+Private = false
+Pages = ["util/topology.jl"]
+```
+
+# Encoding/Decoding
+
+In the following the built-in functions for encoding and decoding messages are listed.
+
+```@autodocs
+Modules = [Mango]
+Private = false
+Pages = ["util/encode_decode.jl"]
+```
+
+# Misc
+
+
+```@autodocs
+Modules = [Mango]
+Private = false
+Pages = ["util/datastructures_util.jl"]
+```

docs/src/assets/theme_overrides.css

@@ -0,0 +1,91 @@
+body {
+  font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI emojiEmoji;
+}
+
+html.theme--documenter-dark body {
+  font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI emojiEmoji;
+}
+
+html.theme--documenter-dark #documenter .docs-sidebar {
+  border-right: none;
+}
+
+html.theme--documenter-dark .select select,
+html.theme--documenter-dark .textarea,
+html.theme--documenter-dark .input,
+html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input {
+  border-color: #2f4547;
+}
+
+#documenter {
+  width: 100%;
+  display: flex;
+}
+
+@media screen and (min-width: 1056px) {
+  #documenter .docs-sidebar {
+    position: sticky;
+    height: 100vh;
+    padding-left: calc(50% - 1200px / 2);
+    display: flex;
+    min-width: 18rem;
+    box-sizing: content-box;
+  }
+
+  html.theme--documenter-dark #documenter .docs-sidebar {
+    position: sticky;
+    height: 100vh;
+    padding-left: calc(50% - 1200px / 2);
+    display: flex;
+    min-width: 18rem;
+    box-sizing: content-box;
+    background-color: #252929;
+  }
+}
+
+html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu .tocitem {
+  background-color: transparent;
+}
+
+@media screen and (min-width: 1056px) {
+  #documenter .docs-main {
+    max-width: 52rem;
+    padding-right: 1rem;
+    margin-left: 50px;
+  }
+
+  html.theme--documenter-dark #documenter .docs-main {
+    max-width: 52rem;
+    padding-right: 1rem;
+    margin-left: 50px;
+  }
+}
+
+#documenter .docs-sidebar .docs-package-name {
+  visibility: hidden;
+  height: 0;
+}
+
+html.theme--documenter-dark .button.is-static {
+  border-color: #2f4547;
+}
+
+html.theme--documenter-dark #documenter .docs-main header.docs-navbar {
+  border-bottom: 1px solid #2f4547;
+}
+
+html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal {
+  border-top: 1px solid #2f4547;
+}
+
+html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active {
+  border-color: #2f4547;
+}
+
+html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu {
+  border-color: #2f4547;
+}
+
+html.theme--documenter-dark #documenter .docs-main .docs-footer {
+  border-color: #2f4547;
+}

docs/src/getting_started.md

@@ -0,0 +1,75 @@
+### Using the sharing ADMM with flex actors (e.g. for resource optimization) with Mango.jl
+
+```julia
+using Mango
+using DistributedResourceOptimization
+
+@role struct HandleOptimizationResultRole
+    got_it::Bool = false
+end
+
+function Mango.handle_message(role::HandleOptimizationResultRole, message::OptimizationFinishedMessage, meta::Any)
+    role.got_it = true
+end
+
+container = create_tcp_container("127.0.0.1", 5555)
+
+# create participant models
+flex_actor = create_admm_flex_actor_one_to_many(10, [0.1, 0.5, -1])
+flex_actor2 = create_admm_flex_actor_one_to_many(15, [0.1, 0.5, -1])
+flex_actor3 = create_admm_flex_actor_one_to_many(10, [0.1, 0.5, -1])
+
+# create coordinator with objective
+coordinator = create_sharing_target_distance_admm_coordinator()
+
+# create roles to integrate admm in Mango.jl
+dor = DistributedOptimizationRole(flex_actor, tid=:custom)
+dor2 = DistributedOptimizationRole(flex_actor2, tid=:custom)
+dor3 = DistributedOptimizationRole(flex_actor3, tid=:custom)
+coord_role = CoordinatorRole(coordinator, tid=:custom, include_self=true)
+
+# role to handle a result
+handle = HandleOptimizationResultRole()
+handle2 = HandleOptimizationResultRole()
+handle3 = HandleOptimizationResultRole()
+
+# create agents
+add_agent_composed_of(container, dor, handle)
+c = add_agent_composed_of(container, dor2, handle2)
+ca = add_agent_composed_of(container, coord_role, dor3, handle3)
+
+# create a topology of the agents
+auto_assign!(complete_topology(3, tid=:custom), container)
+
+# run the simulation with start message and wait for result
+activate(container) do
+    wait(send_message(c, StartCoordinatedDistributedOptimization(create_admm_start(create_admm_sharing_data([0.2, 1, -2]))), address(ca)))
+    wait(coord_role.task)
+end
+```
+
+### Using COHDA with Mango.jl
+
+```julia
+using Mango
+using DistributedResourceOptimization
+
+container = create_tcp_container("127.0.0.1", 5555)
+
+# create agents with local model wrapped in the general distributed optimization role
+agent_one = add_agent_composed_of(container, DistributedOptimizationRole(
+    create_cohda_participant(1, [[0.0, 1, 2], [1, 2, 3]])))
+agent_two = add_agent_composed_of(container, DistributedOptimizationRole(
+    create_cohda_participant(2, [[0.0, 1, 2], [1, 2, 3]])))
+
+# create start message
+initial_message = create_cohda_start_message([1.2, 2, 3])
+
+# create topology
+auto_assign!(complete_topology(2), container)
+
+# run simulation
+activate(container) do
+    send_message(agent_one, initial_message, address(agent_two))
+end
+```

docs/src/index.md

@@ -0,0 +1,15 @@
+# Distributed Resource Optimization for Julia
+
+The package DistributedResourceOptimization.jl (DRO) aims to provide a collection of distributed optimization algorithms for optimizing distributed resources. The algorithms are implemented without considering one special communication technique or package. DRO provides abstract types and function interfaces to implement so-called carriers, which are able to execute the distributed algorithms asynchronous. All algorithms can also be used without carrier using fitting @spawn or @async statements.
+
+Currently there are three tested algorithms:
+* ADMM multi-value consensus such that the sum of all resp values equals a target vector
+* ADMM sharing variant on flexibility providing resources
+* COHDA, Combinatorial Optimization Heuristic for Distributed Agents, which minimizes the distance of schedule sums to a given target schedule
+
+There is one carrier implemented:
+* Mango.jl, agent framework for the simulation of distributed systems, DO provides roles to which the specific algorithms can be assigned to
+
+Note that the package is highly work in progress. 
+
+However, DRO is available on the general Julia registry, and can therfore be installed calling `]add DistributedResourceOptimization`.