Add documentation and update workflows

.github/workflows/CI.yml

@@ -31,12 +31,6 @@ jobs:
             ${{ runner.os }}-test-${{ env.cache-name }}-
             ${{ runner.os }}-test-
             ${{ runner.os }}-
-      - shell: bash
-        env:
-          OPTLICENSE: ${{ secrets.OPTLICENSE }}
-        run: |
-          mkdir -p /opt/gurobi
-          echo "$OPTLICENSE" > /opt/gurobi/gurobi.lic
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
       #- uses: julia-actions/julia-processcoverage@v1

.github/workflows/documentation.yml

@@ -0,0 +1,27 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main # update to match your development branch (master, main, dev, trunk, ...)
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    permissions:
+      contents: write
+      statuses: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1.6'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key
+        run: julia --project=docs/ docs/make.jl

docs/Project.toml

@@ -0,0 +1,20 @@
+[deps]
+Combinatorics = "861a8166-3701-5b0c-9a16-15d98fcdc6aa"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+ExportAll = "ad2082ca-a69e-11e9-38fa-e96309a31fe4"
+FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
+Formatting = "59287772-0a20-5a39-b81b-1366585eb4c0"
+GLPK = "60bf3e95-4087-53dc-ae20-288a0d20c6a6"
+HiGHS = "87dc4568-4c63-4d18-b0c0-bb2238e4078b"
+Ipopt = "b6b21f68-93f8-5de0-b562-5493be1d77c9"
+JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
+JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+ProgressBars = "49802e3a-d2f1-5c88-81d8-b72133a6f568"
+Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+TheoryOfGames = "eb50afb4-6f20-4b37-9b66-473e668300bf"
+YAML = "ddb6d928-2868-570f-bddf-ab3f9cf99eb6"
+
+[compat]
+Documenter = "1.1"

docs/make.jl

@@ -0,0 +1,80 @@
+using TheoryOfGames
+using Documenter
+using Literate
+using Test
+
+# Deactivate Plots display output on server
+ENV["GKSwstype"] = "100"
+
+const _EXAMPLE_DIR = joinpath(@__DIR__, "src", "examples")
+
+"""
+    _include_sandbox(filename)
+Include the `filename` in a temporary module that acts as a sandbox. (Ensuring
+no constants or functions leak into other files.)
+"""
+function _include_sandbox(filename)
+    mod = @eval module $(gensym()) end
+    return Base.include(mod, filename)
+end
+
+function _file_list(full_dir, relative_dir, extension)
+    return map(
+        file -> joinpath(relative_dir, file),
+        filter(file -> endswith(file, extension), sort(readdir(full_dir))),
+    )
+end
+
+function link_example(content)
+    edit_url = match(r"EditURL = \"(.+?)\"", content)[1]
+    footer = match(r"^(---\n\n\*This page was generated using)"m, content)[1]
+    content = replace(
+        content, footer => "!!! info\n    [View this file on Github]($(edit_url)).\n\n" * footer
+    )
+    return content
+end
+
+function literate_directory(dir)
+    rm.(_file_list(dir, dir, ".md"))
+    for filename in _file_list(dir, dir, ".jl")
+        # `include` the file to test it before `#src` lines are removed. It is
+        # in a testset to isolate local variables between files.
+        @testset "$(filename)" begin
+            _include_sandbox(filename)
+        end
+        Literate.markdown(
+            filename,
+            dir;
+            documenter = true,
+            postprocess = link_example
+        )
+    end
+    return
+end
+
+literate_directory(_EXAMPLE_DIR)
+
+makedocs(
+    modules = [TheoryOfGames],
+    doctest  = false,
+    clean    = true,
+    format   = Documenter.HTML(
+        mathengine = Documenter.MathJax2(),
+        prettyurls = get(ENV, "CI", nothing) == "true",
+    ),
+    sitename = "TheoryOfGames.jl",
+    authors  = "Davide Fioriti",
+    pages   = [
+        "Home" => "index.md",
+        "Examples" => [
+            joinpath("examples", f) for
+            f in readdir(_EXAMPLE_DIR) if endswith(f, ".md")
+        ],
+        "API reference" => "API reference.md",
+    ]
+)
+
+deploydocs(
+    repo = "github.com/SPSUnipi/TheoryOfGames.jl.git",
+    push_preview = true,
+)

docs/src/API reference.md

@@ -0,0 +1,6 @@
+# API Reference
+
+```@autodocs
+Modules = [TheoryOfGames]
+Order   = [:function, :type]
+```

docs/src/examples/example_three_users_atleasttwo.jl

@@ -0,0 +1,55 @@
+# # Example 1: Key player but not alone
+# This example aims to describe the simple use of the package for a 3-user case.
+# The major reward allocation techniques supported by the package are considered,
+# using the enumerative technique.
+
+# The sample game considered in this example has the following characteristics:
+# - there are 3 players: 1, 2 and 3
+# - each user can join or not the coalition
+# - the utility value is:
+#   - always 0 if player 1 does not join the coalition
+#   - +1 if player 1 joins the coalition but it is not alone
+
+# In the following, the game is constructed.
+
+# First, the packages are imported
+using TheoryOfGames
+using JuMP, Ipopt
+
+# ## Initialization of the game
+
+# Define the set of the users that can join or not the coalition
+player_set = [1, 2, 3]
+
+# Define the utility function that is a function that:
+# - takes as input an iterable that represents a coalition
+# - it returns a value in agreement to what discussed above and here summarized:
+#   - it returns +1 if player 1 joins the coalition but it is not alone
+#     ``(1 in x) && length(x)``
+#   - it returns 0 if player 1 does not join the coalition (otherwise)
+#     ``else condition`
+utility = x->((1 in x) && (length(x) > 1)) ? 1.0 : 0.0
+
+# Show the value of utility for the coalition where only user 1 joins
+utility([1])
+
+# Show the value if also user 2 joins
+utility([1, 2])
+
+# ## Calculation of selected reward allocation functions
+
+# Define the Enumerative object
+enum_obj = EnumMode(player_set, utility)
+
+# Calculate shapley value
+shapley_value(enum_obj)
+
+# Define the optimizer needed for nucleolus and var least core techniques.
+# We use the default Ipopt and disable the output for simplicity (``print_level=>0``).
+OPTIMIZER = optimizer_with_attributes(Ipopt.Optimizer, "print_level" => 0)
+
+# Calculate nucleolus
+nucleolus(enum_obj, OPTIMIZER)
+
+# Calculate var least core
+var_least_core(enum_obj, OPTIMIZER)

docs/src/index.md

@@ -0,0 +1,13 @@
+# TheoryOfGames.jl Documentation
+
+## Introduction
+
+TheoryOfGames is a package for game-theory applications.
+
+Currently supported functions include the following reward distribution techniques:
+- Shapely Value
+- Core
+- LeastCore
+- Nucleolus
+- VarLeastCore
+- VarCore