Merge pull request #394 from kdayday/docs_cleanup

Docs cleanup (IS portion)
NREL-Sienna · Sep 3, 2024 · 0816ef2 · 0816ef2
2 parents f6de7fd + fefd03a
commit 0816ef2
Show file tree

Hide file tree

Showing 9 changed files with 228 additions and 26 deletions.
diff --git a/src/production_variable_cost_curve.jl b/src/production_variable_cost_curve.jl
@@ -83,7 +83,7 @@ The default units for the x-axis are MW and can be specified with `power_units`.
     value_curve::T
     "(default: natural units (MW)) The units for the x-axis of the curve"
     power_units::UnitSystem = UnitSystem.NATURAL_UNITS
-    "Either a fixed value for fuel cost or the key to a fuel cost time series"
+    "Either a fixed value for fuel cost or the [`TimeSeriesKey`](@ref) to a fuel cost time series"
     fuel_cost::Union{Float64, TimeSeriesKey}
     "(default of 0) Additional proportional Variable Operation and Maintenance Cost in \$/(power_unit h)
     represented as a [`LinearCurve`](@ref)"

diff --git a/src/static_time_series.jl b/src/static_time_series.jl
@@ -1,3 +1,11 @@
+"""
+Supertype for static time series, which has one value per time point
+
+Current concrete subtypes are:
+- [`SingleTimeSeries`](@ref)
+
+See also: [`Forecast`](@ref)
+"""
 abstract type StaticTimeSeries <: TimeSeriesData end
 
 Base.length(ts::StaticTimeSeries) = length(get_data(ts))

diff --git a/src/system_data.jl b/src/system_data.jl
@@ -452,7 +452,7 @@ function iterate_supplemental_attributes_with_time_series(
 end
 
 """
-Returns an iterator of TimeSeriesData instances attached to the system.
+Returns an iterator of `TimeSeriesData` instances attached to the system.
 
 Note that passing a filter function can be much slower than the other filtering parameters
 because it reads time series data from media.
@@ -465,6 +465,13 @@ Call `collect` on the result to get an array.
   - `filter_func = nothing`: Only return time_series for which this returns true.
   - `type = nothing`: Only return time_series with this type.
   - `name = nothing`: Only return time_series matching this value.
+
+See also: [`get_time_series_multiple` from an individual component or attribute](@ref get_time_series_multiple(
+    owner::TimeSeriesOwners,
+    filter_func = nothing;
+    type = nothing,
+    name = nothing,
+))
 """
 function get_time_series_multiple(
     data::SystemData,

diff --git a/src/time_series_interface.jl b/src/time_series_interface.jl
@@ -43,7 +43,14 @@ Does not apply a scaling factor multiplier.
   - `features...`: User-defined tags that differentiate multiple time series arrays for the
     same component attribute, such as different arrays for different scenarios or years
 
-See also: [`get_time_series_array`](@ref), [`get_time_series_values`](@ref).
+See also: [`get_time_series_array`](@ref), [`get_time_series_values`](@ref),
+[`get_time_series` by key](@ref get_time_series(
+    owner::TimeSeriesOwners,
+    key::TimeSeriesKey,
+    start_time::Union{Nothing, Dates.DateTime} = nothing,
+    len::Union{Nothing, Int} = nothing,
+    count::Union{Nothing, Int} = nothing,
+))
 """
 function get_time_series(
     ::Type{T},
@@ -86,6 +93,16 @@ Does not apply a scaling factor multiplier.
     of forecast windows starting at `start_time` to return. Defaults to all available.
   - `features...`: User-defined tags that differentiate multiple time series arrays for the
     same component attribute, such as different arrays for different scenarios or years
+
+See also: [`get_time_series` by name](@ref get_time_series(
+    ::Type{T},
+    owner::TimeSeriesOwners,
+    name::AbstractString;
+    start_time::Union{Nothing, Dates.DateTime} = nothing,
+    len::Union{Nothing, Int} = nothing,
+    count::Union{Nothing, Int} = nothing,
+    features...,
+) where {T <: TimeSeriesData})
 """
 function get_time_series(
     owner::TimeSeriesOwners,
@@ -120,6 +137,13 @@ Call `collect` on the result to get an array.
   - `filter_func = nothing`: Only return time_series for which this returns true.
   - `type = nothing`: Only return time_series with this type.
   - `name = nothing`: Only return time_series matching this value.
+
+See also: [`get_time_series_multiple` from a `System`](@ref get_time_series_multiple(
+    data::SystemData,
+    filter_func = nothing;
+    type = nothing,
+    name = nothing,
+))
 """
 function get_time_series_multiple(
     owner::TimeSeriesOwners,
@@ -210,7 +234,20 @@ features...,) where {T <: TimeSeriesData}),
     len::Union{Nothing, Int} = nothing,
     features...,
 ) where {T <: TimeSeriesData}),
- [`get_time_series`](@ref)
+[`get_time_series_array` from a `StaticTimeSeriesCache`](@ref get_time_series_array(
+    owner::TimeSeriesOwners,
+    time_series::StaticTimeSeries,
+    start_time::Union{Nothing, Dates.DateTime} = nothing;
+    len::Union{Nothing, Int} = nothing,
+    ignore_scaling_factors = false,
+)),
+[`get_time_series_array` from a `ForecastCache`](@ref get_time_series_array(
+    owner::TimeSeriesOwners,
+    forecast::Forecast,
+    start_time::Dates.DateTime;
+    len = nothing,
+    ignore_scaling_factors = false,
+))
 """
 function get_time_series_array(
     ::Type{T},
@@ -271,7 +308,23 @@ See also [`get_time_series_values`](@ref get_time_series_values(
     forecast::Forecast,
     start_time::Union{Nothing, Dates.DateTime} = nothing;
     len::Union{Nothing, Int} = nothing,
-)), [`ForecastCache`](@ref).
+)), [`ForecastCache`](@ref),
+[`get_time_series_array` by name from storage](@ref get_time_series_array(
+    ::Type{T},
+    owner::TimeSeriesOwners,
+    name::AbstractString;
+    start_time::Union{Nothing, Dates.DateTime} = nothing,
+    len::Union{Nothing, Int} = nothing,
+    ignore_scaling_factors = false,
+    features...,
+) where {T <: TimeSeriesData}),
+[`get_time_series_array` from a `StaticTimeSeriesCache`](@ref get_time_series_array(
+    owner::TimeSeriesOwners,
+    time_series::StaticTimeSeries,
+    start_time::Union{Nothing, Dates.DateTime} = nothing;
+    len::Union{Nothing, Int} = nothing,
+    ignore_scaling_factors = false,
+))
 """
 function get_time_series_array(
     owner::TimeSeriesOwners,
@@ -301,7 +354,23 @@ factor multiplier by default.
 
 See also: [`get_time_series_values`](@ref get_time_series_values(owner::TimeSeriesOwners, time_series::StaticTimeSeries, start_time::Union{Nothing, Dates.DateTime} = nothing; len::Union{Nothing, Int} = nothing, ignore_scaling_factors = false)),
 [`get_time_series_timestamps`](@ref get_time_series_timestamps(owner::TimeSeriesOwners, time_series::StaticTimeSeries, start_time::Union{Nothing, Dates.DateTime} = nothing; len::Union{Nothing, Int} = nothing,)),
-[`StaticTimeSeriesCache`](@ref).
+[`StaticTimeSeriesCache`](@ref),
+[`get_time_series_array` by name from storage](@ref get_time_series_array(
+    ::Type{T},
+    owner::TimeSeriesOwners,
+    name::AbstractString;
+    start_time::Union{Nothing, Dates.DateTime} = nothing,
+    len::Union{Nothing, Int} = nothing,
+    ignore_scaling_factors = false,
+    features...,
+) where {T <: TimeSeriesData}),
+[`get_time_series_array` from a `ForecastCache`](@ref get_time_series_array(
+    owner::TimeSeriesOwners,
+    forecast::Forecast,
+    start_time::Dates.DateTime;
+    len = nothing,
+    ignore_scaling_factors = false,
+))
 """
 function get_time_series_array(
     owner::TimeSeriesOwners,
@@ -352,7 +421,19 @@ See also: [`get_time_series_array`](@ref get_time_series_array(
     start_time::Union{Nothing, Dates.DateTime} = nothing,
     len::Union{Nothing, Int} = nothing,
     ignore_scaling_factors = false,
-features...,) where {T <: TimeSeriesData})
+features...,) where {T <: TimeSeriesData}),
+[`get_time_series_timestamps` from a `StaticTimeSeriesCache`](@ref get_time_series_timestamps(
+    owner::TimeSeriesOwners,
+    time_series::StaticTimeSeries,
+    start_time::Union{Nothing, Dates.DateTime} = nothing;
+    len::Union{Nothing, Int} = nothing,
+)),
+[`get_time_series_timestamps` from a `ForecastCache`](@ref get_time_series_timestamps(
+    owner::TimeSeriesOwners,
+    forecast::Forecast,
+    start_time::Union{Nothing, Dates.DateTime} = nothing;
+    len::Union{Nothing, Int} = nothing,
+))
 """
 function get_time_series_timestamps(
     ::Type{T},
@@ -397,7 +478,21 @@ See also: [`get_time_series_array`](@ref get_time_series_array(
     start_time::Dates.DateTime;
     len::Union{Nothing, Int} = nothing,
     ignore_scaling_factors = false,
-)), [`ForecastCache`](@ref).
+)), [`ForecastCache`](@ref),
+[`get_time_series_timestamps` by name from storage](@ref get_time_series_timestamps(
+    ::Type{T},
+    owner::TimeSeriesOwners,
+    name::AbstractString;
+    start_time::Union{Nothing, Dates.DateTime} = nothing,
+    len::Union{Nothing, Int} = nothing,
+    features...,
+) where {T <: TimeSeriesData}),
+[`get_time_series_timestamps` from a `StaticTimeSeriesCache`](@ref get_time_series_timestamps(
+    owner::TimeSeriesOwners,
+    time_series::StaticTimeSeries,
+    start_time::Union{Nothing, Dates.DateTime} = nothing;
+    len::Union{Nothing, Int} = nothing,
+))
 """
 function get_time_series_timestamps(
     owner::TimeSeriesOwners,
@@ -428,7 +523,21 @@ See also: [`get_time_series_array`](@ref get_time_series_array(
     len::Union{Nothing, Int} = nothing,
     ignore_scaling_factors = false,
 )), [`get_time_series_values`](@ref get_time_series_values(owner::TimeSeriesOwners, time_series::StaticTimeSeries, start_time::Union{Nothing, Dates.DateTime} = nothing; len::Union{Nothing, Int} = nothing, ignore_scaling_factors = false)),
-[`StaticTimeSeriesCache`](@ref).
+[`StaticTimeSeriesCache`](@ref),
+[`get_time_series_timestamps` by name from storage](@ref get_time_series_timestamps(
+    ::Type{T},
+    owner::TimeSeriesOwners,
+    name::AbstractString;
+    start_time::Union{Nothing, Dates.DateTime} = nothing,
+    len::Union{Nothing, Int} = nothing,
+    features...,
+) where {T <: TimeSeriesData}),
+[`get_time_series_timestamps` from a `ForecastCache`](@ref get_time_series_timestamps(
+    owner::TimeSeriesOwners,
+    forecast::Forecast,
+    start_time::Union{Nothing, Dates.DateTime} = nothing;
+    len::Union{Nothing, Int} = nothing,
+))
 """
 function get_time_series_timestamps(
     owner::TimeSeriesOwners,
@@ -478,7 +587,21 @@ See also: [`get_time_series_array`](@ref get_time_series_array(
     len::Union{Nothing, Int} = nothing,
     features...,
 ) where {T <: TimeSeriesData}),
-[`get_time_series`](@ref)
+[`get_time_series`](@ref),
+[`get_time_series_values` from a `StaticTimeSeriesCache`](@ref get_time_series_values(
+    owner::TimeSeriesOwners,
+    time_series::StaticTimeSeries,
+    start_time::Union{Nothing, Dates.DateTime} = nothing;
+    len::Union{Nothing, Int} = nothing,
+    ignore_scaling_factors = false,
+)),
+[`get_time_series_values` from a `ForecastCache`](@ref get_time_series_values(
+    owner::TimeSeriesOwners,
+    forecast::Forecast,
+    start_time::Dates.DateTime;
+    len::Union{Nothing, Int} = nothing,
+    ignore_scaling_factors = false,
+))
 """
 function get_time_series_values(
     ::Type{T},
@@ -527,7 +650,23 @@ See also: [`get_time_series_array`](@ref get_time_series_array(
     forecast::Forecast,
     start_time::Union{Nothing, Dates.DateTime} = nothing;
     len::Union{Nothing, Int} = nothing,
-)), [`ForecastCache`](@ref).
+)), [`ForecastCache`](@ref),
+[`get_time_series_values` by name from storage](@ref get_time_series_values(
+    ::Type{T},
+    owner::TimeSeriesOwners,
+    name::AbstractString;
+    start_time::Union{Nothing, Dates.DateTime} = nothing,
+    len::Union{Nothing, Int} = nothing,
+    ignore_scaling_factors = false,
+    features...,
+) where {T <: TimeSeriesData}),
+[`get_time_series_values` from a `StaticTimeSeriesCache`](@ref get_time_series_values(
+    owner::TimeSeriesOwners,
+    time_series::StaticTimeSeries,
+    start_time::Union{Nothing, Dates.DateTime} = nothing;
+    len::Union{Nothing, Int} = nothing,
+    ignore_scaling_factors = false,
+))
 """
 function get_time_series_values(
     owner::TimeSeriesOwners,
@@ -567,7 +706,23 @@ See also: [`get_time_series_array`](@ref get_time_series_array(
     len::Union{Nothing, Int} = nothing,
     ignore_scaling_factors = false,
 )), [`get_time_series_timestamps`](@ref get_time_series_timestamps(owner::TimeSeriesOwners, time_series::StaticTimeSeries, start_time::Union{Nothing, Dates.DateTime} = nothing; len::Union{Nothing, Int} = nothing,)),
-[`StaticTimeSeriesCache`](@ref).
+[`StaticTimeSeriesCache`](@ref),
+[`get_time_series_values` by name from storage](@ref get_time_series_values(
+    ::Type{T},
+    owner::TimeSeriesOwners,
+    name::AbstractString;
+    start_time::Union{Nothing, Dates.DateTime} = nothing,
+    len::Union{Nothing, Int} = nothing,
+    ignore_scaling_factors = false,
+    features...,
+) where {T <: TimeSeriesData}),
+[`get_time_series_values` from a `ForecastCache`](@ref get_time_series_values(
+    owner::TimeSeriesOwners,
+    forecast::Forecast,
+    start_time::Dates.DateTime;
+    len::Union{Nothing, Int} = nothing,
+    ignore_scaling_factors = false,
+))
 """
 function get_time_series_values(
     owner::TimeSeriesOwners,

diff --git a/src/time_series_storage.jl b/src/time_series_storage.jl
@@ -4,13 +4,13 @@ Abstract type for time series storage implementations.
 
 All subtypes must implement:
 
-  - clear_time_series!
-  - deserialize_time_series
-  - get_compression_settings
-  - get_num_time_series
-  - remove_time_series!
-  - serialize_time_series!
-  - Base.isempty
+  - `clear_time_series!`
+  - `deserialize_time_series`
+  - `get_compression_settings`
+  - `get_num_time_series`
+  - `remove_time_series!`
+  - `serialize_time_series!`
+  - `Base.isempty`
 """
 abstract type TimeSeriesStorage end
 

diff --git a/src/time_series_structs.jl b/src/time_series_structs.jl
@@ -1,9 +1,17 @@
 const TimeSeriesOwners = Union{InfrastructureSystemsComponent, SupplementalAttribute}
 
-# Required methods:
-# - get_name
-# - get_time_series_type
-# The default methods rely on the field names name and time_series_type.
+"""
+Supertype for keys that can be used to access a desired time series dataset
+
+Concrete subtypes:
+- [`StaticTimeSeriesKey`](@ref)
+- [`ForecastKey`](@ref)
+
+Required methods:
+- `get_name`
+- `get_time_series_type`
+The default methods rely on the field names `name` and `time_series_type`.
+"""
 abstract type TimeSeriesKey <: InfrastructureSystemsType end
 
 get_name(key::TimeSeriesKey) = key.name
@@ -24,6 +32,11 @@ function deserialize_struct(T::Type{<:TimeSeriesKey}, data::Dict)
     return T(; vals...)
 end
 
+"""
+A unique key to identify and retrieve a [`StaticTimeSeries`](@ref)
+
+See: [`get_time_series_keys`](@ref) and [`get_time_series(::TimeSeriesOwners, ::TimeSeriesKey)`](@ref).
+"""
 @kwdef struct StaticTimeSeriesKey <: TimeSeriesKey
     time_series_type::Type{<:StaticTimeSeries}
     name::String
@@ -44,6 +57,11 @@ function make_time_series_key(metadata::StaticTimeSeriesMetadata)
     )
 end
 
+"""
+A unique key to identify and retrieve a [`Forecast`](@ref)
+
+See: [`get_time_series_keys`](@ref) and [`get_time_series(::TimeSeriesOwners, ::TimeSeriesKey)`](@ref).
+"""
 @kwdef struct ForecastKey <: TimeSeriesKey
     time_series_type::Type{<:Forecast}
     name::String

diff --git a/src/utils/logging.jl b/src/utils/logging.jl
@@ -317,7 +317,13 @@ Base.flush(logger::FileLogger) = flush(logger.logger.stream)
 Base.close(logger::FileLogger) = close(logger.logger.stream)
 
 """
-Opens a file logger using Logging.SimpleLogger.
+Opens a file logger using `Logging.SimpleLogger`.
+
+# Arguments
+  - `func::Function`
+  - `filename::String`: logger filename
+  - `level=Logging.Info`: optional, to change the minimum logging level
+  - `mode = "w+"`: Optional, to designate write mode
 
 # Example
 
@@ -584,7 +590,7 @@ function set_group_level!(logger::MultiLogger, group::Symbol, level::Base.LogLev
 end
 
 """
-Set the minimum log levels for multiple groups. Refer to [`set_group_level`](@ref) for more
+Set the minimum log levels for multiple groups. Refer to [`set_group_level!`](@ref) for more
 information.
 """
 function set_group_levels!(logger::MultiLogger, group_levels::Dict{Symbol, Base.LogLevel})