Updated documentations (#35)

* Updated type docstrings

* Updated documentation index

* Updated documentation quick start

NEWS.md

@@ -2,7 +2,8 @@
 
 ## Unversioned
 
-* Use dev version of EMB for examples when running as part of tests (#33)
+* Updated minor issues in the documentation (docstrings, indices, and quick start).
+* Use dev version of EMB for examples when running as part of tests, solving [Issue #17](https://github.com/EnergyModelsX/EnergyModelsBase.jl/issues/17).
 
 ## Version 0.7.0 (2024-05-24)
 

docs/src/how-to/update-models.md

@@ -9,7 +9,7 @@ We will as well implement information regarding the adjustment of extension pack
 
 ### Key changes for nodal descriptions
 
-Version 0.7 introduced both *[storage behaviours](@ref sec_lib_public_storbehav)* resulting in a rework of the individual approach for calculating the level balance as well as the potential to have charge and discharge capacities through _[storage parameters](@ref sec_lib_public_storpar)_.
+Version 0.7 introduced both *[storage behaviours](@ref sec_lib_public_storbehav)* resulting in a rework of the individual approach for calculating the level balance as well as the potential to have charge and discharge capacities through *[storage parameters](@ref sec_lib_public_storpar)*.
 
 !!! note
     The legacy constructors for calls of the composite type of version 0.6 will be included at least until version 0.8.

docs/src/index.md

@@ -36,7 +36,7 @@ Pages = [
     "manual/constraint-functions.md",
     "manual/data-functions.md",
     "manual/simple-example.md",
-    "manual/simple-example.md",
+    "manual/NEWS.md",
 ]
 Depth = 1
 ```

docs/src/library/internals/reference.md

@@ -1,18 +1,21 @@
 # Internals
 
 ## Index
+
 ```@index
 Pages = ["reference.md"]
 ```
 
 ## Types
+
 ```@autodocs
 Modules = [EnergyModelsBase]
 Public = false
 Order = [:type]
 ```
 
 ## Methods
+
 ```@autodocs
 Modules = [EnergyModelsBase]
 Public = false

docs/src/library/public.md

@@ -334,9 +334,12 @@ process_emissions
 The periods can either be either and `AbstractStrategicPeriod` or `AbstractRepresentativePeriod`.
 In the former case, it is however not fully used as the last strategic period is not relevant for the level balances.
 
+Both composite types allow only `EMB.NothingPeriod` types as input to the individual fields.
+
 ```@docs
 PreviousPeriods
 CyclicPeriods
+EMB.NothingPeriod
 ```
 
 The individual fields can be accessed through the following functions:

docs/src/manual/quick-start.md

@@ -6,10 +6,3 @@
 >     ] add TimeStruct
 >     ] add EnergyModelsBase
 >     ```
-
-!!! note
-    If you receive the error that `EnergyModelsBase` is not yet registered, you have to add the package using the GitHub repositories through
-    ```
-    ] add https://github.com/EnergyModelsX/EnergyModelsBase.jl
-    ```
-    Once the package is registered, this is not required.

src/legacy_constructor.jl

@@ -16,7 +16,7 @@ This version will be discontinued in the near future and replaced with the new v
 `RefStorage{StorageBehavior}` in which the parametric input defines the behaviour of the
 storage.
 
-See the _[documentation](https://energymodelsx.github.io/EnergyModelsBase.jl/stable/how-to/update-models.html)_
+See the *[documentation](https://energymodelsx.github.io/EnergyModelsBase.jl/stable/how-to/update-models)*
 for further information regarding how you can translate your existing model to the new model.
 """
 function RefStorage(
@@ -35,7 +35,7 @@ function RefStorage(
         "The used implementation of a `RefStorage` will be discontinued in the near future. " *
         "See the documentation for the new implementation using a parametric type describing " *
         "the storage behaviour and the changes incorporated for level and charge through using " *
-        "the types `StorageBehavior` and `AbstractStorageParameters` in the scetion on " *
+        "the types `StorageBehavior` and `AbstractStorageParameters` in the section on " *
         "_How to update your model to the latest versions_.\n" *
         "In practice, two changes have to be incorporated: \n 1. `RefStorage{AccumulatingEmissions}()` " *
         "instead of `RefStorage` and \n 2. the application of `StorCapOpex(rate_cap, opex_var, opex_fixed)` " *
@@ -111,7 +111,7 @@ This version will be discontinued in the near future and replaced with the new v
 `RefStorage{StorageBehavior}` in which the parametric input defines the behaviour of the
 storage.
 
-See the _[documentation](https://energymodelsx.github.io/EnergyModelsBase.jl/stable/how-to/update-models.html)_
+See the *[documentation](https://energymodelsx.github.io/EnergyModelsBase.jl/stable/how-to/update-models)*
 for further information regarding how you can translate your existing model to the new model.
 """
 function RefStorage(
@@ -134,7 +134,7 @@ function RefStorage(
         "_How to update your model to the latest versions_.\n" *
         "In practice, two changes have to be incorporated: \n 1. `RefStorage{CyclicStrategic}()` " *
         "instead of `RefStorage` and \n 2. the application of `StorCapOpexVar(rate_cap, opex_var)` " *
-        "as 2ⁿᵈ field as well as `StorCapOpexFixed(stor_cap, opex_var, opex_fixed)` as 3ʳᵈ " *
+        "as 2ⁿᵈ field as well as `StorCapOpexFixed(stor_cap, opex_fixed)` as 3ʳᵈ " *
         "field instead of using `rate_cap`, `stor_cap`, `opex_var`, and `opex_fixed` as " *
         "2ⁿᵈ-5ᵗʰ fields.\n" *
         "It is recommended to update the existing implementation to the new version.",
@@ -171,7 +171,7 @@ function RefStorage(
         "_How to update your model to the latest versions_.\n" *
         "In practice, two changes have to be incorporated: \n 1. `RefStorage{CyclicStrategic}()` " *
         "instead of `RefStorage` and \n 2. the application of `StorCapOpexVar(rate_cap, opex_var)` " *
-        "as 2ⁿᵈ field as well as `StorCapOpexFixed(stor_cap, opex_var, opex_fixed)` as 3ʳᵈ " *
+        "as 2ⁿᵈ field as well as `StorCapOpexFixed(stor_cap, opex_fixed)` as 3ʳᵈ " *
         "field instead of using `rate_cap`, `stor_cap`, `opex_var`, and `opex_fixed` as " *
         "2ⁿᵈ-5ᵗʰ fields.\n" *
         "It is recommended to update the existing implementation to the new version.",

src/model.jl

@@ -76,7 +76,7 @@ These variables are:
   [storage parameters](@ref sec_lib_public_storpar) used in the field `:charge`.
   This variable is only defined if the `Storage` node has a field `charge.`
 * `:stor_discharge_use` - storage discharging use in each operational period.
-* `:stor_discharge_inst` - installed charging capacity, e.g. power, in each operational period,
+* `:stor_discharge_inst` - installed discharging capacity, e.g. power, in each operational period,
   constrained in the operational case to the provided capacity in the
   [storage parameters](@ref sec_lib_public_storpar) used in the field `:discharge`.
   This variable is only defined if the `Storage` node has a field `discharge.`

src/structures/data.jl

@@ -11,21 +11,21 @@ Abstract type for `EmissionsData` can be used to dispatch on different types of
 capture configurations.
 
 In general, the different types require the following input:
-- **`emissions::Dict{ResourceEmit, T}`**: Emissions per unit produced. It allows for \
-an input as `TimeProfile` or `Float64`.\n
-- **`co2_capture::Float64`**: CO₂ capture rate.\n
+- **`emissions::Dict{ResourceEmit, T}`**: Emissions per unit produced. It allows for
+  an input as `TimeProfile` or `Float64`.
+- **`co2_capture::Float64`**: CO₂ capture rate.
 
 # Types
-- **`CaptureProcessEnergyEmissions`**: Capture both the process emissions and the \
-energy usage related emissions.\n
-- **`CaptureProcessEmissions`**: Capture the process emissions, but not the \
-energy usage related emissions.\n
-- **`CaptureEnergyEmissions`**: Capture the energy usage related emissions, but not the \
-process emissions. Does not require `emissions` as input.\n
-- **`EmissionsProcess`**: No capture, but process emissions are present. \
-Does not require `co2_capture` as input, but will ignore it, if provided.\n
-- **`EmissionsEnergy`**: No capture and no process emissions. Does not require \
-`co2_capture` or `emissions` as input, but will ignore them, if provided.\n
+- **`CaptureProcessEnergyEmissions`**: Capture both the process emissions and the
+  energy usage related emissions.
+- **`CaptureProcessEmissions`**: Capture the process emissions, but not the
+  energy usage related emissions.
+- **`CaptureEnergyEmissions`**: Capture the energy usage related emissions, but not the
+  process emissions. Does not require `emissions` as input.
+- **`EmissionsProcess`**: No capture, but process emissions are present.
+  Does not require `co2_capture` as input, but will ignore it, if provided.
+- **`EmissionsEnergy`**: No capture and no process emissions. Does not require
+  `co2_capture` or `emissions` as input, but will ignore them, if provided.
 """
 
 """ `EmissionsData` as supertype for all `Data` types for emissions."""
@@ -34,10 +34,12 @@ abstract type EmissionsData{T} <: Data end
 abstract type CaptureData{T} <: EmissionsData{T} end
 
 """
+    CaptureProcessEnergyEmissions{T} <: CaptureData{T}
+
 Capture both the process emissions and the energy usage related emissions.
 
 # Fields
-- **`emissions::Dict{ResourceEmit, T}`**: emissions per unit produced.\n
+- **`emissions::Dict{ResourceEmit, T}`** are the process emissions per unit produced.
 - **`co2_capture::Float64`** is the CO₂ capture rate.
 """
 struct CaptureProcessEnergyEmissions{T} <: CaptureData{T}
@@ -46,10 +48,12 @@ struct CaptureProcessEnergyEmissions{T} <: CaptureData{T}
 end
 
 """
+    CaptureProcessEmissions{T} <: CaptureData{T}
+
 Capture the process emissions, but not the energy usage related emissions.
 
 # Fields
-- **`emissions::Dict{ResourceEmit, T}`**: emissions per unit produced.\n
+- **`emissions::Dict{ResourceEmit, T}`** are the process emissions per unit produced.
 - **`co2_capture::Float64`** is the CO₂ capture rate.
 """
 struct CaptureProcessEmissions{T} <: CaptureData{T}
@@ -58,11 +62,13 @@ struct CaptureProcessEmissions{T} <: CaptureData{T}
 end
 
 """
+    CaptureEnergyEmissions{T} <: CaptureData{T}
+
 Capture the energy usage related emissions, but not the process emissions.
 Does not require `emissions` as input, but can be supplied.
 
 # Fields
-- **`emissions::Dict{ResourceEmit, T}`**: emissions per unit produced.\n
+- **`emissions::Dict{ResourceEmit, T}`** are the process emissions per unit produced.
 - **`co2_capture::Float64`** is the CO₂ capture rate.
 """
 struct CaptureEnergyEmissions{T} <: CaptureData{T}
@@ -73,11 +79,13 @@ CaptureEnergyEmissions(co2_capture::Float64) =
     CaptureEnergyEmissions(Dict{ResourceEmit, Float64}(), co2_capture)
 
 """
+    EmissionsProcess{T} <: EmissionsData{T}
+
 No capture, but process emissions are present. Does not require `co2_capture` as input,
 but accepts it and will ignore it, if provided.
 
 # Fields
-- **`emissions::Dict{ResourceEmit, T}`**: emissions per unit produced.\n
+- **`emissions::Dict{ResourceEmit, T}`**: emissions per unit produced.
 """
 struct EmissionsProcess{T} <: EmissionsData{T}
     emissions::Dict{<:ResourceEmit,T}
@@ -86,6 +94,8 @@ EmissionsProcess(emissions::Dict{<:ResourceEmit,T}, _) where {T} = EmissionsProc
 EmissionsProcess() = EmissionsProcess(Dict{ResourceEmit, Float64}())
 
 """
+    EmissionsEnergy{T} <: EmissionsData{T}
+
 No capture, no process emissions are present. Does not require `co2_capture` or `emissions`
 as input, but accepts it and will ignore it, if provided.
 """
@@ -97,18 +107,21 @@ EmissionsEnergy() = EmissionsEnergy{Float64}()
 
 """
     co2_capture(data::CaptureData)
+
 Returns the CO₂ capture rate of the `data`.
 """
 co2_capture(data::CaptureData) = data.co2_capture
 
 """
     process_emissions(data::EmissionsData)
-Returns the `ResourceEmit`s that have process emissions in the `data`.
+
+Returns the [`ResourceEmit`](@ref)s that have process emissions of the [`EmissionsData`](@ref).
 """
 process_emissions(data::EmissionsData) = collect(keys(data.emissions))
 
 """
     process_emissions(data::EmissionsData{T}, p::ResourceEmit)
+
 Returns the the process emissions of resource `p` in the `data` as `TimeProfile`.
 If the process emissions are provided as `Float64`, it returns a `FixedProfile(x)`.
 If there are no process emissions, it returns a `FixedProfile(0)`.

src/structures/link.jl

@@ -13,11 +13,11 @@ Base.show(io::IO, l::Link) = print(io, "l_$(l.from)-$(l.to)")
 A direct link between two nodes.
 
 # Fields
-- **`id`** is the name/identifier of the link.\n
-- **`from::Node`** is node from which there is flow into the link.\n
-- **`to::Node`** is node to which there is flow out of the link.\n
-- **`formulation::Formulation`** is the used formulation of links. If not specified, \
-a `Linear` link is assumed.\n
+- **`id`** is the name/identifier of the link.
+- **`from::Node`** is node from which there is flow into the link.
+- **`to::Node`** is node to which there is flow out of the link.
+- **`formulation::Formulation`** is the used formulation of links. If not specified, a
+  `Linear` link is assumed.
 
 """
 struct Direct <: Link

src/structures/misc.jl

@@ -1,3 +1,8 @@
+"""
+Union of `Nothing`, `TS.TimePeriod`, and `TS.TimeStructure{T} where {T}` to be used for
+limiting the potential entries to the fields of [`PreviousPeriods`](@ref) and
+[`CyclicPeriods`](@ref) types.
+"""
 NothingPeriod = Union{Nothing, TS.TimePeriod, TS.TimeStructure{T}} where {T}
 
 """
@@ -30,7 +35,7 @@ Extracts the previous representative period (fields `sp`) from a [`PreviousPerio
 """
 rep_per(prev_periods::PreviousPeriods) = prev_periods.rp
 """
-    op_perop_per(prev_periods::PreviousPeriods)
+    op_per(prev_periods::PreviousPeriods)
 
 Extracts the previous operational period (fields `sp`) from a [`PreviousPeriods`](@ref) type.
 """

src/structures/model.jl

@@ -2,14 +2,16 @@
 abstract type EnergyModel end
 
 """
+    OperationalModel <: EnergyModel
+
 Operational Energy Model without investments.
 
 # Fields
-- **`emission_limit::Dict{<:ResourceEmit, <:TimeProfile}`** is a dictionary with \
-individual emission limits as `TimeProfile` for each emission resource `ResourceEmit`.\n
-- **`emission_price::Dict{<:ResourceEmit, <:TimeProfile}`** are the prices for the \
-different emissions types considered.\n
-- **`co2_instance`** is a `ResourceEmit` and corresponds to the type used for CO₂.\n
+- **`emission_limit::Dict{<:ResourceEmit, <:TimeProfile}`** is a dictionary with
+  individual emission limits as `TimeProfile` for each emission resource [`ResourceEmit`](@ref).
+- **`emission_price::Dict{<:ResourceEmit, <:TimeProfile}`** are the prices for the
+  different emissions types considered.
+- **`co2_instance`** is a [`ResourceEmit`](@ref) and corresponds to the type used for CO₂.
 """
 struct OperationalModel <: EnergyModel
     emission_limit::Dict{<:ResourceEmit, <:TimeProfile}
@@ -21,20 +23,21 @@ end
     emission_limit(model::EnergyModel)
 
 Returns the emission limit of EnergyModel `model` as dictionary with `TimeProfile`s for
-each `ResourceEmit`.
+each [`ResourceEmit`](@ref).
 """
 emission_limit(model::EnergyModel) = model.emission_limit
 """
     emission_limit(model::EnergyModel, p::ResourceEmit)
 
-Returns the emission limit of EnergyModel `model` and ResourceEmit `p` as `TimeProfile`.
+Returns the emission limit of EnergyModel `model` and [`ResourceEmit`](@ref) `p` as
+`TimeProfile`.
 """
 emission_limit(model::EnergyModel, p::ResourceEmit) = model.emission_limit[p]
 """
     emission_limit(model::EnergyModel, p::ResourceEmit, t_inv::TS.StrategicPeriod)
 
-Returns the emission limit of EnergyModel `model` and ResourceEmit `p` in strategic period
-period `t_inv`.
+Returns the emission limit of EnergyModel `model` and [`ResourceEmit`](@ref) `p`
+in strategic period period `t_inv`.
 """
 emission_limit(model::EnergyModel, p::ResourceEmit, t_inv::TS.StrategicPeriod) =
     model.emission_limit[p][t_inv]
@@ -43,7 +46,7 @@ emission_limit(model::EnergyModel, p::ResourceEmit, t_inv::TS.StrategicPeriod) =
     emission_price(model::EnergyModel)
 
 Returns the emission price of EnergyModel `model` as dictionary with `TimeProfile`s for
-each `ResourceEmit`.
+each [`ResourceEmit`](@ref).
 """
 emission_price(model::EnergyModel) = model.emission_price
 """