Restructuring of the documentation (#22)

* Reworked the documentation structure
* Added consistent labels to all headings
* Added pages for the individual nodes
* Updated the tests based on recent approaches
* Reworking on field functions
---------

Co-authored-by: hellemo <[email protected]>

.gitignore

@@ -10,6 +10,7 @@
 # Build artifacts for creating documentation generated by the Documenter package
 docs/build/
 docs/site/
+docs/src/manual/NEWS.md
 
 # File generated by Pkg, the package manager, based on a corresponding Project.toml
 # It records a fixed state of all packages used by the project. As such, it should not be

NEWS.md

@@ -1,7 +1,10 @@
 # Release notes
 
-## Unversioned
+## Version 0.6.1 (2024-09-03)
 
+* Dependency increase for `EnergyModelsBase` as the changes do not directly affect `EnergyModelsCO2`.
+* Updated the documentation using the new structure released by `EnergyModelsCO2`.
+* Included the package `DocumenterInterLinks` for crossreferences to `EnergyModelsBase`.
 * Use dev version of EMRP for examples when running as part of tests, similar to [PR #33 of EMB](https://github.com/EnergyModelsX/EnergyModelsBase.jl/pull/33).
 
 ## Version 0.6.0 (2024-05-28)

Project.toml

@@ -1,16 +1,15 @@
 name = "EnergyModelsRenewableProducers"
 uuid = "b007c34f-ba52-4995-ba37-fffe79fbde35"
 authors = ["Sigmund Eggen Holm <[email protected]>, Julian Straus <[email protected]>"]
-version = "0.6.0"
+version = "0.6.1"
 
 [deps]
 EnergyModelsBase = "5d7e687e-f956-46f3-9045-6f5a5fd49f50"
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
-Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 TimeStruct = "f9ed5ce0-9f41-4eaa-96da-f38ab8df101c"
 
 [compat]
-EnergyModelsBase = "^0.7.0"
+EnergyModelsBase = "0.8"
 JuMP = "1.5"
-TimeStruct = "^0.8.0"
-julia = "^1.6"
+TimeStruct = "0.8"
+julia = "1.9"

docs/Project.toml

@@ -1,5 +1,6 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
 EnergyModelsBase = "5d7e687e-f956-46f3-9045-6f5a5fd49f50"
 EnergyModelsRenewableProducers = "b007c34f-ba52-4995-ba37-fffe79fbde35"
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"

docs/make.jl

@@ -1,5 +1,7 @@
 using Documenter
+using DocumenterInterLinks
 
+using TimeStruct
 using EnergyModelsBase
 using EnergyModelsRenewableProducers
 
@@ -16,32 +18,44 @@ DocMeta.setdocmeta!(
 news = "docs/src/manual/NEWS.md"
 cp("NEWS.md", news; force=true)
 
+links = InterLinks(
+    "TimeStruct" => "https://sintefore.github.io/TimeStruct.jl/stable/",
+    "EnergyModelsBase" => "https://energymodelsx.github.io/EnergyModelsBase.jl/stable/",
+)
+
 makedocs(
-    modules = [EnergyModelsRenewableProducers],
     sitename = "EnergyModelsRenewableProducers",
+    modules = [EnergyModelsRenewableProducers],
     format = Documenter.HTML(
         prettyurls = get(ENV, "CI", "false") == "true",
         edit_link = "main",
         assets = String[],
+        ansicolor = true,
     ),
     pages = [
         "Home" => "index.md",
         "Manual" => Any[
             "Quick Start" => "manual/quick-start.md",
-            "Optimization variables" => "manual/optimization-variables.md",
-            "Constraint functions" => "manual/constraint-functions.md",
             "Examples" => "manual/simple-example.md",
             "Release notes" => "manual/NEWS.md",
         ],
+        "Nodes" => Any[
+            "Non-dispatchable RES" => "nodes/nondisres.md",
+            "Hydropower" => "nodes/hydropower.md",
+        ],
         "How to" => Any[
             "Update models" => "how-to/update-models.md",
             "Contribute to EnergyModelsRenewableProducers" => "how-to/contribute.md",
         ],
         "Library" => Any[
             "Public" => "library/public.md",
-            "Internals" => "library/internals.md",
+            "Internals" => String[
+                "library/internals/methods-fields.md",
+                "library/internals/methods-EMB.md"
+            ],
         ],
     ],
+    plugins=[links],
 )
 
 deploydocs(;

docs/src/how-to/contribute.md

@@ -1,8 +1,8 @@
-# Contribute to EnergyModelsRenewableProducers
+# [Contribute to EnergyModelsRenewableProducers](@id how_to-con)
 
 Contributing to `EnergyModelsRenewableProducers` can be achieved in several different ways.
 
-## File a bug report
+## [File a bug report](@id how_to-con-bug_rep)
 
 Another approach to contributing to `EnergyModelsRenewableProducers` is through filing a bug report as an [_issue_](https://github.com/EnergyModelsX/EnergyModelsRenewableProducers.jl/issues/new) when unexpected behaviour is occuring.
 
@@ -21,7 +21,7 @@ When filing a bug report, please follow the following guidelines:
 2. Label the issue as bug, and
 3. Provide a minimum working example of a case in which the bug occurs.
 
-## Feature requests
+## [Feature requests](@id how_to-con-feat_req)
 
 `EnergyModelsRenewableProducers` includes several new nodal descriptions for renewable energy producers.
 However, there can be a demand for additional requirements for the existing nodes or for new descriptions which fall below the umbrella of renewable energy producers.

docs/src/index.md

@@ -1,29 +1,44 @@
 # EnergyModelsRenewableProducers
 
-```@docs
-EnergyModelsRenewableProducers
-```
+This Julia package implements three new nodes with corresponding JuMP variables and constraints, extending the package [`EnergyModelsBase`](https://energymodelsx.github.io/EnergyModelsBase.jl/) with more detailed representation of *renewable energy sources*.
+
+These nodes are
+
+1. a `Source` node [`NonDisRES`](@ref),
+2. a `Storage` node ([`HydroStor`](@ref)), and
+3. a `Storage` node ([`PumpedHydroStor`](@ref)).
+
+The new introduced node types are also documented in the *[public library](@ref lib-pub)* as well as the corresponding nodal page.
 
-This Julia package implements two main nodes with corresponding JuMP constraints, extending the package
-[`EnergyModelsBase`](https://energymodelsx.github.io/EnergyModelsBase.jl/)
-with more detailed representation of *renewable energy sources*.
+## Developed nodes
 
-The first node, [`NonDisRES`](@ref), models a non-dispatchable renewable energy source, like wind power, solar power, or run of river hydropower.
+### [`NonDisRES`](@ref)
+
+The first node models a non-dispatchable renewable energy source, like wind power, solar power, or run of river hydropower.
 These all use intermittent energy sources in the production of energy, so the maximum production capacity varies with the availability of the energy source at the time.
 
-The other node implements a regulated hydropower storage plant, both with ([`PumpedHydroStor`](@ref)) and without pumps ([`HydroStor`](@ref)) for filling the reservoir with excess energy.
-The hydropower storage plant can also be extended as they are declared as subtypes of [`HydroStorage`](@ref).
+### [`HydroStor`](@ref) and [`PumpedHydroStor`](@ref)
 
-The new introduced node types are also documented in the *[public library](@ref sec_lib_public)*.
+The other nodes implement a regulated hydropower storage plant, both with ([`PumpedHydroStor`](@ref)) and without pumps ([`HydroStor`](@ref)) for filling the reservoir with excess energy.
+The hydropower storage plant can also be extended as they are declared as subtypes of [`HydroStorage`](@ref).
 
 ## Manual outline
 
 ```@contents
 Pages = [
     "manual/quick-start.md",
-    "manual/optimization-variables.md",
-    "manual/constraint-functions.md",
-    "manual/simple-example.md"
+    "manual/simple-example.md",
+    "manual/NEWS.md",
+]
+Depth = 1
+```
+
+## Description of the nodes
+
+```@contents
+Pages = [
+    "nodes/nondisres.md",
+    "nodes/hydropower.md",
 ]
 Depth = 1
 ```
@@ -42,8 +57,9 @@ Depth = 1
 
 ```@contents
 Pages = [
-    "library/public.md"
-    "library/internals.md"
+    "library/public.md",
+    "library/internals/methods-fields.md",
+    "library/internals/methods-EMB.md",
 ]
 Depth = 1
 ```

docs/src/library/internals/methods-EMB.md

@@ -0,0 +1,28 @@
+# Methods - `EnergyModelsBase`
+
+## Index
+
+```@index
+Pages = ["methods-EMB.md"]
+```
+
+## Extension methods
+
+```@docs
+EnergyModelsBase.variables_node
+EnergyModelsBase.create_node
+```
+
+## Constraint methods
+
+```@docs
+EnergyModelsBase.constraints_capacity
+EnergyModelsBase.constraints_flow_in
+EnergyModelsBase.constraints_level_aux
+```
+
+## Check methods
+
+```@docs
+EnergyModelsBase.check_node
+```

docs/src/library/internals/methods-fields.md

@@ -0,0 +1,28 @@
+
+# Methods - Accessing fields
+
+## Index
+
+```@index
+Pages = ["methods-fields.md"]
+```
+
+## `NonDisRES`
+
+```@docs
+EnergyModelsRenewableProducers.profile
+```
+
+## `HydroStorage`
+
+```@docs
+EnergyModelsRenewableProducers.level_init
+EnergyModelsRenewableProducers.level_inflow
+EnergyModelsRenewableProducers.level_min
+```
+
+## `PumpedHydroStor`
+
+```@docs
+EnergyModelsRenewableProducers.opex_var_pump
+```

docs/src/library/public.md

@@ -1,62 +1,29 @@
-# [Public interface](@id sec_lib_public)
+# [Public interface](@id lib-pub)
 
-## [`NonDisRES` (non-dispatchable renewable energy source)](@id NonDisRES_public)
-
-This type models both wind power, solar power, and run of river hydropower.
-These have in common that they generate power from an intermittent energy source, so they can have large variations in power output, based on the availability of the renewable source at the time.
-These power sources can be modelled using the same type [`NonDisRES`](@ref).
-The new type is a subtype of `EMB.Source`. The new type only differs from its supertype through the field `profile`.
-
-The field `profile::TimeProfile` is a dimensionless ratio (between 0 and 1) describing how much of the installed capacity is utilized at the current operational period.
-Therefore, when using [`NonDisRES`](@ref) to model some renewable source, the data provided to this field is what defines the intermittent characteristics of the source.
-
-The [`NonDisRES`](@ref) node is modelled very similar to a regular `EMB.Source}` node. The only difference is how the intermittent nature of the non-dispatchable source is handled. The maximum power generation of the source in the operational period ``t`` depends on the time-dependent `Profile` variable.
-
-!!! note
-    If not needed, the production does not need to run at full capacity. The amount of energy *not* produced is computed using the non-negative [optimization variable](@ref optimization_variables) ``\texttt{curtailment}`` (declared for [`NonDisRES`](@ref) nodes only).
-
-The fields of the different types are listed below:
+## [Module](@id lib-pub-module)
 
 ```@docs
-NonDisRES
+EnergyModelsRenewableProducers
 ```
 
-## [`HydroStorage` (regulated hydro storage with or without pump)](@id HydroStorage_public)
-
-A hydropower plant is much more flexible than, *e.g.*, a wind farm since the water can be stored for later use.
-Energy can be produced (almost) whenever it is needed.
-Some hydropower plants also have pumps installed.
-These are used to pump water into the reservoir when excess and cheap energy is available in the network.
-`EnergyModelsRenewableProducers` introduces hence two different types representing a regulated hydropower plant ([`HydroStor`](@ref)) and a pumped regulated hydropower plant ([`PumpedHydroStor`](@ref)) without a lower reservoir.
-Both types have a `level` and `discharge` capacity while a `PumpedHydroStor` also includes a `charge` capacity.
+## [Node types](@id lib-pub-node)
 
-The variable `level_init` represents the initial energy available in the reservoir in the beginning of each investment period.
-The variable `level_inflow` describes the inflow into the reservoir (measured in energy units), while `level_min` is the allowed minimum storage level in the dam, given as a ratio of the installed storage capacity of the reservoir at
-every operational period.
-The required minimum level is enforced by NVE and varies over the year.
-The resources stored in the hydro storage is set as `stor_res`, similar to a regular `EMB.RefStorage`.
+### [Abstract types](@id lib-pub-node-abstract)
 
-The five last parameters are used in the same way as in `EMB.Storage`.
-In the implementation of [`PumpedHydroStor`](@ref), the values set in `input` represents a loss of energy when using the pumps.
-A value of `1` means no energy loss, while a value of `0` represents 100% energy loss of that inflow variable.
+```@docs
+HydroStorage
+```
 
-The fields of the different types are listed below:
+### [Concrete types](@id lib-pub-node-concrete)
 
 ```@docs
-HydroStorage
+NonDisRES
 HydroStor
 PumpedHydroStor
 ```
 
-In recent version increases, we changed the individual fields of the `HydroStorage` nodes as well as their types.
-Hence, we still incorporate legacy constructors that can be utilized when having a model in previous versions.
-However, we removed one legacy constructor as it is no longer required.
-Calling the constructor will provide you now with an error.
-
-This legacy constructor is:
+### [Legacy constructors](@id lib-pub-node-legacy)
 
 ```@docs
 RegHydroStor
 ```
-
-See the section on *[how to update models](@ref update-models)* for further information regarding how you can translate your existing model to the new model.

docs/src/manual/NEWS.md

@@ -1,5 +1,9 @@
 # Release notes
 
+## Unversioned
+
+* Use dev version of EMRP for examples when running as part of tests, similar to [PR #33 of EMB](https://github.com/EnergyModelsX/EnergyModelsBase.jl/pull/33).
+
 ## Version 0.6.0 (2024-05-28)
 
 * Adjusted to changes introduced in `EnergyModelsBase` v0.7.