Merge pull request #3 from ait-energy/dev

Updates to documentation

README.md

@@ -1,8 +1,10 @@
-# Integrated Energy System Optimization (IESopt.jl)
+# IESopt: Integrated Energy System Optimization
 
 [![License](https://img.shields.io/github/license/ait-energy/IESopt.jl)](LICENSE)
-[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://ait-energy.github.io/IESopt.jl/stable/)
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://ait-energy.github.io/IESopt.jl/dev/)
+<!--
+[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://ait-energy.github.io/IESopt.jl/stable/)
+-->
 
 [![Build Status](https://github.com/ait-energy/IESopt.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/ait-energy/IESopt.jl/actions/workflows/CI.yml?query=branch%3Amain)
 [![Coverage](https://codecov.io/gh/ait-energy/IESopt.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/ait-energy/IESopt.jl)
@@ -25,30 +27,105 @@ systems.
 
 ## Background
 
-TODO
+IESopt has been in development at AIT since 2021, and was moved to GitHub in June, 2024, based on a cleaned version with
+slightly more than 1000 commits. Check out the [references](https://ait-energy.github.io/IESopt.jl/dev/pages/references/publications/)
+for a more detailed overview about publications and projects, where IESopt has been used.
 
 ## Install
 
-TODO: Document how to install the package.
+Make sure to check out the detailed [installation guides](https://ait-energy.github.io/IESopt.jl/dev/pages/tutorials/setup/)
+in the documentation, both for Python and Julia.
+
+### Quick setup for Julia
+
+In an open REPL, type `]` to enter the package mode, make sure that your environment is
+activated (e.g., do `activate .`), then add the package with the following command:
+
+```bash
+(your-env) pkg> add IESopt
+```
+
+### Quick setup for Python
+
+Head over to [iesopt-py](https://github.com/ait-energy/iesopt-py) and follow the instructions there, or - if you already
+have a working Python environment - install the package, e.g., via `poetry`:
+
+```bash
+poetry add iesopt-py
+```
 
 ## Usage
 
-TODO: Document how to use the package.
+IESopt requires a configured model to run. You can start with the extensive [first model tutorial](https://ait-energy.github.io/IESopt.jl/dev/pages/tutorials/first_model/), or checkout [IESoptLib](https://github.com/ait-energy/IESoptLib.jl) which
+includes many more examples.
+
+### Basic usage
+
+The basic workflow to get results from a model, defined by a top-level configuration file `config.iesopt.yaml`, is as
+follows:
+
+1. Parse, generate, and build the model from `config.iesopt.yaml`.
+2. Optimize the model (the chose solver is specified in `config.iesopt.yaml`).
+3. Get the results from the model.
+
+Steps 1. and 2. can be combined in a single call, which the convenience function `run(...)` provides.
+
+#### Using Julia
+
+```julia
+using IESopt
+
+model = IESopt.run("config.iesopt.yaml")
+results = model.ext[:iesopt].results
+```
+
+#### Using Python
+
+```python
+import iesopt
+
+model = iesopt.run("config.iesopt.yaml")
+df_results = model.results.to_pandas()
+```
 
 ## API
 
-TODO: Document the API of the package.
+Check out the full [API reference](https://ait-energy.github.io/IESopt.jl/dev/pages/manual/api/) in the
+documentation.
+
+### Basic API
+
+A short overview is given below.
+
+#### Julia API
+
+```julia
+"""Builds and returns a model using the IESopt framework."""
+IESopt.generate!(filename::String)
+
+"""Optimize the given model, optionally saving model results to disk."""
+IESopt.optimize!(model::JuMP.Model; save_results::Bool=true, kwargs...)
+
+"""Build, optimize, and return a model, in a single call."""
+IESopt.run(filename::String; verbosity=nothing, kwargs...)
+
+"""Get the component with the name `component_name` from the `model`."""
+IESopt.component(model::JuMP.Model, component_name::String)
+
+"""Compute the Irreducible Infeasible Set (IIS) of the model."""
+IESopt.compute_IIS(model::JuMP.Model; filename::String = "")
+```
 
-### Python
+### Python API
 
-### Julia
+To be added.
 
 ## Contributing
 
 [![Code Style](https://img.shields.io/badge/code_style-custom-blue?style=flat&logo=julia&logoColor=white)](.JuliaFormatter.toml)
 [![Readme Style](https://img.shields.io/badge/readme_style-standard-lime?style=flat&logo=julia&logoColor=white)](https://github.com/RichardLitt/standard-readme)
 
-PRs accepted.
+PRs accepted. Checkout the [developer documentation](https://ait-energy.github.io/IESopt.jl/dev/pages/dev_docs/).
 
 ## License
 

RELEASING.md

@@ -0,0 +1,111 @@
+# Releasing
+
+This documents the steps necessary to release a new version of the IESopt.jl package. Follow these step-by-step, and fix
+any issues that might arise, before proceeding to the next step:
+
+1. [Check tests locally](#check-tests-locally)
+2. [Check formatting](#check-formatting)
+3. [Update the changelog](#update-the-changelog)
+4. [Update the version number](#update-the-version-number)
+5. [Trigger a new release](#trigger-a-new-release)
+
+## Check tests locally
+
+After entering "package mode" (press `]`), make sure that the `IESopt` environment is activated, which shows as
+`(IESopt) pkg>` (if not execute `activate .`), and then run the tests by executing the `test` command:
+
+```shell
+(IESopt) pkg> test
+```
+
+## Check formatting
+
+The following assumes that you have installed the `JuliaFormatter.jl` package.
+
+<details>
+<summary>Expand: How to install <b><i>JuliaFormatter</i></b></summary>
+
+> It is advised to add that package to your "base" environment (it comes at little overhead, and is then available in
+> all environments). To install the package, run the following command in the Julia REPL, after switching to "package
+> mode" (press `]`):
+>
+> ```shell
+> (......) pkg> activate
+> (@v1.10) pkg> add JuliaFormatter
+> ```
+>
+> The first "empty" activate command is necessary to switch to the "base" environment (it acts like `conda deactivate`).
+> The second command then installs the `JuliaFormatter.jl` package (note that `(@v1.10)` is just an example, it could be
+> different for you).
+
+</details>
+
+To check/fix the formatting of the package, run the following command in the Julia REPL:
+
+```julia
+using JuliaFormatter
+format("src")
+```
+
+This automatically formats all files in the `src` directory. This returns `true` if all files were already formatted
+correctly.
+
+## Update the changelog
+
+Check out [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) for guidance on how to write a changelog. You can use
+the template below, replace all placeholders, and remove the parts that are not applicable. Add the new entry as topmost
+entry of the [CHANGELOG.md](CHANGELOG.md) file.
+
+<details>
+<summary>Expand: Changelog template</summary>
+
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+
+{{Give a (really) short description of the release here, ideally one sentence.}}
+
+### Added
+
+- {{document new features here}}
+
+### Changed
+
+- {{document changed features here}}
+
+### Deprecated
+
+- {{document deprecated features here}}
+
+### Removed
+
+- {{document removed features here}}
+
+### Fixed
+
+- {{document fixed bugs here}}
+```
+
+</details>
+
+## Update the version number
+
+Update the version number in the [Project.toml](Project.toml) file. The version number should be in the format `X.Y.Z`.
+Check the [Semantic Versioning](https://semver.org/spec/v2.0.0.html) specification for guidance on how to update the
+version number. Make sure to name your commit as:
+
+```text
+chore: prep for vX.Y.Z
+```
+
+## Trigger a new release
+
+Open the latest commit that was merged into the `main` branch (this should be a `chore: prep for vX.Y.Z` commit) and add
+a comment with the following text:
+
+```text
+@JuliaRegistrator register
+
+Release notes:
+
+{{>> directly add you new changelog entry here <<}}
+```

codecov.yml

@@ -0,0 +1,15 @@
+coverage:
+  status:
+    project:
+      default:
+        target: auto
+        threshold: 0%
+        base: auto 
+
+comment:
+  layout: "diff, flags, files"
+  behavior: default
+  require_changes: false
+  require_base: false
+  require_head: true
+  hide_project_coverage: false

docs/changelog.jl

@@ -7,7 +7,7 @@ function create_changelog()
 
     # Write the changelog.
     open(joinpath(PATH_DOCS, "src", "pages", "changelog.md"), "w") do f
-        write(f, changelog)
+        return write(f, changelog)
     end
 end
 

docs/generate.jl

@@ -3,15 +3,8 @@ _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
-
+    isa(entry.second, String) && return entry.first => joinpath(parent, "$(_canonify_string(entry.second)).md")
     return entry.first => _build_page_paths(entry.second; parent=joinpath(parent, _canonify_string(entry.first)))
 end
 
@@ -21,22 +14,26 @@ examples_files = [
     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",
+_PAGES = Pair["Home" => "index.md"]
+append!(
+    _PAGES,
+    _build_page_paths(
+        [
+            "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"],
+            "References" => "references",
+            "Developer Documentation" => "dev_docs",
+            "Changelog" => "changelog",
+        ];
+        parent="pages",
+    ),
 )
 
 # Create `changelog.md` from `CHANGELOG.md`.

docs/liveserver.jl

@@ -3,8 +3,8 @@
 # julia --project=. -e 'include("docs/liveserver.jl")'
 # ```
 
-const PATH_ROOT = dirname(@__DIR__)
-const PATH_DOCS = joinpath(PATH_ROOT, "docs")
+const LS_PATH_ROOT = dirname(@__DIR__)
+const LS_PATH_DOCS = joinpath(LS_PATH_ROOT, "docs")
 
 # Make sure `docs` environment is set up properly.
 import Pkg
@@ -17,17 +17,17 @@ 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_dirs=[
+        joinpath(LS_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)
+    include_files=[
+        joinpath(LS_PATH_DOCS, "generate.jl"),   # watch `generate.jl` for changes (to regenerate docs)
+        joinpath(LS_PATH_DOCS, "changelog.jl"),  # watch `changelog.jl` for changes (to regenerate changelog)
+        joinpath(LS_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` 
+    skip_files=[
+        joinpath(LS_PATH_DOCS, "src", "pages", "changelog.md"),  # don't watch this, because it's generated by `generate.jl` 
     ],
-    launch_browser = true,
-    verbose = true,
+    launch_browser=true,
+    verbose=true,
 )