Trying PR from dev to main

.JuliaFormatter.toml

@@ -1 +1,13 @@
-# See https://domluna.github.io/JuliaFormatter.jl/stable/ for a list of options
+# Configuration file for JuliaFormatter.jl
+# For more information, see: https://domluna.github.io/JuliaFormatter.jl/stable/config/
+# This is (loosely) based on the formatting that https://github.com/jump-dev/JuMP.jl uses
+
+always_for_in = true
+always_use_return = true
+margin = 120
+remove_extra_newlines = true
+separate_kwargs_with_semicolon = true
+short_to_long_function_def = false
+whitespace_typedefs = true
+whitespace_in_kwargs = false
+whitespace_ops_in_indices = true

.gitignore

@@ -4,3 +4,4 @@
 /Manifest.toml
 /docs/Manifest.toml
 /docs/build/
+/docs/src/pages/changelog.md

CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2023-06-01
+
+### Added
+
+- Initial public release of IESopt.jl

Project.toml

@@ -1,7 +1,56 @@
 name = "IESopt"
 uuid = "ed3f0a38-8ad9-4cf8-877e-929e8d190fe9"
-authors = ["Stefan Strömer <stefan.stroemer@ait.ac.at> and contributors"]
 version = "1.0.0"
 
+[deps]
+ArgCheck = "dce04be8-c92d-5529-be00-80e4d2c0e197"
+CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
+Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
+HiGHS = "87dc4568-4c63-4d18-b0c0-bb2238e4078b"
+IESoptLib = "b98f706d-40ec-4ce6-a66c-1c6e71d3cef6"
+JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
+JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
+JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
+LibGit2 = "76f85450-5226-5b5a-8eaa-529ad045b433"
+Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
+LoggingExtras = "e6f89c97-d47a-5376-807f-9c37f3926c36"
+Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
+MultiObjectiveAlgorithms = "0327d340-17cd-11ea-3e99-2fd5d98cecda"
+OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
+Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
+PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
+Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
+ProgressMeter = "92933f4c-e287-5a05-a399-4b506db050ca"
+RuntimeGeneratedFunctions = "7e49a35a-f44a-4d26-94aa-eba1b4ca6b47"
+Suppressor = "fd094767-a336-5f1f-9728-57cf17d0bbfb"
+Tectonic = "9ac5f52a-99c6-489f-af81-462ef484790f"
+YAML = "ddb6d928-2868-570f-bddf-ab3f9cf99eb6"
+ZipFile = "a5390f91-8eb1-5f08-bee0-b1d1ffed6cea"
+
 [compat]
+ArgCheck = "2.3.0"
+CSV = "0.10"
+DataFrames = "1.6"
+Dates = "<0.0.1,1"
+HiGHS = "1.9"
+IESoptLib = "0.1"
+JLD2 = "0.4"
+JSON = "0.21"
+JuMP = "1.22"
+LibGit2 = "<0.0.1,1"
+Logging = "<0.0.1,1"
+LoggingExtras = "1.0"
+Markdown = "<0.0.1,1"
+MultiObjectiveAlgorithms = "1.3"
+OrderedCollections = "1.6"
+Pkg = "1.10"
+PrecompileTools = "1.2"
+Printf = "<0.0.1,1"
+ProgressMeter = "1.10"
+RuntimeGeneratedFunctions = "0.5.13"
+Suppressor = "0.2"
+Tectonic = "0.8"
+YAML = "0.4"
+ZipFile = "0.10"
 julia = "1.9"

README.md

@@ -13,6 +13,9 @@
 **IESopt** (_Integrated Energy System Optimization_) is a modeling and optimization framework for integrated energy
 systems.
 
+> Note: We are currently moving from our internal version control to GitHub. Missing contents will be added during the
+> upcoming days ...
+
 ## Table of Contents
 
 - [Background](#background)
@@ -28,15 +31,15 @@ TODO
 
 ## Install
 
-TODO: Documment how to install the package.
+TODO: Document how to install the package.
 
 ## Usage
 
-TODO: Documment how to use the package.
+TODO: Document how to use the package.
 
 ## API
 
-TODO: Documment the API of the package.
+TODO: Document the API of the package.
 
 ### Python
 

docs/Project.toml

@@ -1,3 +1,5 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 IESopt = "ed3f0a38-8ad9-4cf8-877e-929e8d190fe9"
+IESoptLib = "b98f706d-40ec-4ce6-a66c-1c6e71d3cef6"
+LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"

docs/changelog.jl

@@ -0,0 +1,14 @@
+function create_changelog()
+    PATH_ROOT = dirname(@__DIR__)
+    PATH_DOCS = joinpath(PATH_ROOT, "docs")
+
+    # Read the changelog file.
+    changelog = read(joinpath(PATH_ROOT, "CHANGELOG.md"), String)
+
+    # Write the changelog.
+    open(joinpath(PATH_DOCS, "src", "pages", "changelog.md"), "w") do f
+        write(f, changelog)
+    end
+end
+
+create_changelog()

docs/generate.jl

@@ -0,0 +1,43 @@
+_canonify_string(str::String) = lowercase(replace(str, r"[^a-zA-Z0-9]" => "_"))
+
+function _build_page_paths(entry; parent::String)
+    isa(entry, String) && return joinpath(parent, "$(_canonify_string(entry)).md")
+    isa(entry, AbstractVector) && return [_build_page_paths(subentry; parent=parent) for subentry in entry]
+
+    isa(entry, Pair) || error("Invalid type of entry in page structure")
+
+    isa(entry.second, String) && return entry.first => "$(_canonify_string(entry.second)).md"
+
+    if isa(entry.second, AbstractVector) && length(entry.second) == 1
+        return joinpath(parent, "$(_canonify_string(entry.second[1])).md")
+    end
+
+    return entry.first => _build_page_paths(entry.second; parent=joinpath(parent, _canonify_string(entry.first)))
+end
+
+# This defines the order of the menu / page structure.
+examples_files = [
+    file[1:(end - 3)] for
+    file in readdir(normpath(@__DIR__, "src", "pages", "user_guide", "examples")) if endswith(file, ".md")
+]
+
+_PAGES = _build_page_paths(
+    [
+        "Home" => "index",
+        "Tutorials" => ["setup", "first_model", "next_steps", "results"],
+        "User Guide" => [
+            "general",
+            "Sectors" => ["electricity", "heat", "gas"],
+            "solvers",
+            "Custom Functionality" => ["templates", "addons"],
+            "Examples" => [], # TODO: examples_files,
+        ],
+        "Manual" => ["yaml", "core_components", "templates", "api"],
+        "Developer Documentation" => ["dev_docs"],
+        "Changelog" => ["changelog"],
+    ];
+    parent="pages",
+)
+
+# Create `changelog.md` from `CHANGELOG.md`.
+include("changelog.jl")

docs/liveserver.jl

@@ -0,0 +1,33 @@
+# Build and serve the documentation locally, with live updates, by using this file:
+# ```shell
+# julia --project=. -e 'include("docs/liveserver.jl")'
+# ```
+
+const PATH_ROOT = dirname(@__DIR__)
+const PATH_DOCS = joinpath(PATH_ROOT, "docs")
+
+# Make sure `docs` environment is set up properly.
+import Pkg
+Pkg.activate(@__DIR__)
+Pkg.instantiate()
+
+# Communicate with `make.jl` that we are running in live mode, so that we can load `Revise` there.
+push!(ARGS, "running_local_liveserver")
+
+# Serve documentation now.
+import LiveServer
+LiveServer.servedocs(;
+    include_dirs = [
+        joinpath(PATH_ROOT, "src"),           # watch `src/` for changes (to update docstrings)
+    ],
+    include_files = [
+        joinpath(PATH_DOCS, "generate.jl"),   # watch `generate.jl` for changes (to regenerate docs)
+        joinpath(PATH_DOCS, "changelog.jl"),  # watch `changelog.jl` for changes (to regenerate changelog)
+        joinpath(PATH_ROOT, "CHANGELOG.md"),  # watch `CHANGELOG.md` for changes (to regenerate changelog)
+    ],
+    skip_files = [
+        joinpath(PATH_DOCS, "src", "pages", "changelog.md"),  # don't watch this, because it's generated by `generate.jl` 
+    ],
+    launch_browser = true,
+    verbose = true,
+)

docs/make.jl

@@ -1,23 +1,49 @@
+const is_local_draft = "running_local_liveserver" in ARGS
+const running_in_ci = haskey(ENV, "CI") || haskey(ENV, "GITHUB_ACTIONS")
+
+if is_local_draft
+    try
+        import Revise
+        Revise.revise()
+    catch
+        @warn "Building documentation without Revise support. If you want to automatically refresh docstrings from withing IESopt.jl, you need Revise installed."
+    end
+end
+
 using IESopt
 using Documenter
 
-# DocMeta.setdocmeta!(IESopt, :DocTestSetup, :(using IESopt); recursive=true)
+# Set up, and generate everything as needed.
+include("generate.jl")
 
+# Build documentation.
 makedocs(;
-    modules=[IESopt],
+    sitename="-- IESopt --",
     authors="Stefan Strömer (@sstroemer), Daniel Schwabeneder (@daschw), and contributors",
-    sitename="IESopt.jl",
     format=Documenter.HTML(;
         canonical="https://ait-energy.github.io/IESopt.jl",
         edit_link="dev",
-        assets=String[],
+        prettyurls=true,
+        collapselevel=2,
+        mathengine=Documenter.MathJax2(),
+        highlights=["yaml", "python"],
+        assets=[
+            asset("assets/base_template.css"; class=:css, islocal=true),
+        ],
+        size_threshold=300_000,
+        size_threshold_warn=200_000,
     ),
-    pages=[
-        "Home" => "index.md",
-    ],
+    pages=_PAGES,
+    doctest = false,
+    pagesonly = true,
+    warnonly = true,
+    draft = is_local_draft,
 )
 
-deploydocs(;
-    repo="github.com/ait-energy/IESopt.jl",
-    devbranch="dev",
-)
+# Deploy documentation, if we are not running locally.
+if !is_local_draft
+    deploydocs(;
+        repo="github.com/ait-energy/IESopt.jl",
+        devbranch="dev",
+    )
+end

docs/src/assets/base_template.css

@@ -0,0 +1,15 @@
+@media screen and (min-width: 1056px) {
+    .docs-main {
+        max-width: 65rem !important;
+    }
+
+    .content {
+        text-align: justify;
+    }
+}
+
+img.center {
+    display: block;
+    margin-left: auto;
+    margin-right: auto;
+}

docs/src/index.md

@@ -1,14 +1,77 @@
+# IESopt.jl
+
+_**Integrated Energy System Optimization** framework written in Julia._
+
+## Introduction
+
+`IESopt.jl` is the core of the IESopt framework, developed at [AIT Austrian Institute of Technology GmbH](https://www.ait.ac.at/).
+It is written in Julia, and uses [JuMP](https://github.com/jump-dev/JuMP.jl) package to construct the underlying
+mathematical optimization models, and to interface with various solvers. The model is designed to be modular, and allows
+for easy extension and customization.
+
 ```@meta
-CurrentModule = IESopt
+# TODO: add "The main functionalities of IESopt.jl are: ..." itemize here.
+# TODO: add gitter here
+# TODO: cleanup the "About" section, and integrate it here
 ```
 
-# IESopt
+Check out the following GitHub repositories for more information:
 
-Documentation for [IESopt](https://github.com/ait-energy/IESopt.jl).
+- [IESopt.jl](https://github.com/ait-energy/IESopt.jl), the core model (a Julia package).
+- [iesopt-py](https://github.com/ait-energy/iesopt-py), the Python interface.
 
-```@index
-```
+!!! danger "Moving to open-source"
+    We are currently working (hard) on getting IESopt fully open-source on GitHub, which requires some clean-up of
+    (potentially) confindential left-overs (e.g., from projects). Meanwhile, a lot of internals are changing (after
+    staying fixed for a long time), and the documentation needs to be checked page-by-page. If you are trying to
+    get started before we manage to fix everything, get in touch with us directly - we'll help you set up everything you
+    need. The documentation currently consists of mostly structured pages, with the content being added as soon as
+    possible.
+
+## Installation
+
+!!! details "Using Python"
+    To be added.
+
+!!! details "Using Julia"
+    To be added.
+
+## Citation
+
+If you find IESopt useful in your work, and are intend to publish or document your modeling, we kindly request that you
+include the following citation:
+
+- **Style: APA7**
+  > Strömer, S., Schwabeneder, D., & contributors. (2021-2024). _IESopt: Integrated Energy System Optimization_ [Software]. AIT Austrian Institute of Technology GmbH. [https://github.com/ait-energy/IESopt](https://github.com/ait-energy/IESopt)
+- **Style: IEEE**
+  > [1] S. Strömer, D. Schwabeneder, and contributors, _"IESopt: Integrated Energy System Optimization,"_ AIT Austrian Institute of Technology GmbH, 2021-2024. [Online]. Available: [https://github.com/ait-energy/IESopt](https://github.com/ait-energy/IESopt)
+- **BibTeX:**
+  ```bibtex
+  @misc{iesopt,
+      author = {Strömer, Stefan and Schwabeneder, Daniel and contributors},
+      title = {{IES}opt: Integrated Energy System Optimization},
+      organization = {AIT Austrian Institute of Technology GmbH},
+      url = {https://github.com/ait-energy/IESopt},
+      type = {Software},
+      year = {2021-2024},
+  }
+  ```
+
+```@meta
+# ## About
+
+# ### Overview
+
+# IESopt, _Integrated Energy System Optimization_, is a general purpose energy system optimization framework, developed at the [Center for Energy](https://www.ait.ac.at/en/about-the-ait/center/center-for-energy), at [AIT Austrian Institute of Technology GmbH](https://www.ait.ac.at/), mainly developed and maintained by the unit [Integrated Energy Systems](https://www.ait.ac.at/en/research-topics/integrated-energy-systems).
+
+# ### Feature summary
+
+# What IESopt is, may be, and is not:
 
-```@autodocs
-Modules = [IESopt]
+# - YES
+#   - IESopt is a general purpose energy system (optimization) model. It supports multiple solvers (using `JuMP.jl` to interface with them) as well as a standardized way to build up models using "core components".
+# - MAYBE
+#   - IESopt.jl is not branded as JuMP extension. It plays nicely with JuMP, and some extensions, but we currently do not see it as a fully fledged JuMP extension. That, e.g., entails that `copy_extension_data` is not implemented at the moment, so `copy_model` is not supported. This is a deliberate choice, and may be changed in the - near or far - future.
+# - NO (really ...)
+#   - A full energy system model, in the sense of "containing data". There are a lot of good, and open, data sources out there from other teams, consider using them.
 ```