Merge pull request #1143 from kdayday/missing_docstrings

Add missing docstrings, update to Documenter 1.7, format markdown files

.github/ISSUE_TEMPLATE/bug_report.md

@@ -10,7 +10,6 @@ assignees: ''
 **If this is a question, something isn't working or an idea please start a Q&A discussion in the [Discussion tab](https://github.com/NREL-Sienna/PowerSimulations.jl/discussions)**
 Open a bug report only if you can provide the details below
 
-
 **Describe the bug**
 A clear and concise description of what the bug is.
 

CONTRIBUTING.md

@@ -1,6 +1,7 @@
 # Contributing
 
 Community driven development of this package is encouraged. To maintain code quality standards, please adhere to the following guidelines when contributing:
- - To get started, <a href="https://www.clahub.com/agreements/NREL/PowerSimulations.jl">sign the Contributor License Agreement</a>.
- - Please do your best to adhere to the lengthy [Julia style guide](https://docs.julialang.org/en/latest/manual/style-guide/).
- - To submit code contributions, [fork](https://help.github.com/articles/fork-a-repo/) the repository, commit your changes, and [submit a pull request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/).
+
+  - To get started, <a href="https://www.clahub.com/agreements/NREL/PowerSimulations.jl">sign the Contributor License Agreement</a>.
+  - Please do your best to adhere to the lengthy [Julia style guide](https://docs.julialang.org/en/latest/manual/style-guide/).
+  - To submit code contributions, [fork](https://help.github.com/articles/fork-a-repo/) the repository, commit your changes, and [submit a pull request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/).

README.md

@@ -9,24 +9,23 @@
 
 `PowerSimulations.jl` is a Julia package for power system modeling and simulation of Power Systems operations. The objectives of the package are:
 
-- Provide a flexible modeling framework that can accommodate problems of different complexity and at different time-scales.
+  - Provide a flexible modeling framework that can accommodate problems of different complexity and at different time-scales.
 
-- Streamline the construction of large scale optimization problems to avoid repetition of work when adding/modifying model details.
-
-- Exploit Julia's capabilities to improve computational performance of large scale power system quasi-static simulations.
+  - Streamline the construction of large scale optimization problems to avoid repetition of work when adding/modifying model details.
+  - Exploit Julia's capabilities to improve computational performance of large scale power system quasi-static simulations.
 
 The flexible modeling framework is enabled through a modular set of capabilities that enable scalable power system analysis and exploration of new analysis methods. The modularity of PowerSimulations results from the structure of the simulations enabled by the package:
 
-- _Simulations_ define a set of problems that can be solved using numerical techniques.
+  - _Simulations_ define a set of problems that can be solved using numerical techniques.
 
 For example, an annual production cost modeling simulation can be created by formulating a unit commitment model against system data to assemble a set of 365 daily time-coupled scheduling problems.
 
 ## Simulations enabled by PowerSimulations
 
-- Integrated Resource Planning
-- Production Cost Modeling
-- Market Simulations
-  
+  - Integrated Resource Planning
+  - Production Cost Modeling
+  - Market Simulations
+
 ## Installation
 
 ```julia
@@ -50,4 +49,4 @@ Contributions to the development and enhancement of PowerSimulations is welcome.
 
 ## License
 
-PowerSimulations is released under a BSD [license](https://github.com/NREL-Sienna/PowerSimulations.jl/blob/main/LICENSE). PowerSimulations has been developed as part of the Scalable Integrated Infrastructure Planning (SIIP) initiative at the U.S. Department of Energy's National Renewable Energy Laboratory ([NREL](https://www.nrel.gov/)) Software Record SWR-23-104. 
+PowerSimulations is released under a BSD [license](https://github.com/NREL-Sienna/PowerSimulations.jl/blob/main/LICENSE). PowerSimulations has been developed as part of the Scalable Integrated Infrastructure Planning (SIIP) initiative at the U.S. Department of Energy's National Renewable Energy Laboratory ([NREL](https://www.nrel.gov/)) Software Record SWR-23-104.

docs/Project.toml

@@ -16,7 +16,6 @@ PowerSystems = "bcd98974-b02a-5e2f-9ee0-a103f5c450dd"
 TimeSeries = "9e3dc215-6440-5c97-bce1-76c03772f85e"
 
 [compat]
-Documenter = "0.27"
+Documenter = "^1.7"
 InfrastructureSystems = "2"
 julia = "^1.6"
-Latexify = "=0.16.3"

docs/make.jl

@@ -29,6 +29,7 @@ pages = OrderedDict(
     "Code Base Developer Guide" => Any[
         "Developer Guide" => "code_base_developer_guide/developer.md",
         "Troubleshooting" => "code_base_developer_guide/troubleshooting.md",
+        "Internals" => "code_base_developer_guide/internal.md",
     ],
     "Formulation Library" => Any[
         "Introduction" => "formulation_library/Introduction.md",
@@ -47,9 +48,11 @@ pages = OrderedDict(
 
 makedocs(;
     modules = [PowerSimulations],
-    format = Documenter.HTML(; prettyurls = haskey(ENV, "GITHUB_ACTIONS")),
+    format = Documenter.HTML(;
+        prettyurls = haskey(ENV, "GITHUB_ACTIONS"),
+        size_threshold = nothing),
     sitename = "PowerSimulations.jl",
-    authors = "Jose Daniel Lara, Daniel Thom and Clayton Barrows",
+    authors = "Jose Daniel Lara, Daniel Thom, Kate Doubleday, Rodrigo Henriquez-Auba, and Clayton Barrows",
     pages = Any[p for p in pages],
 )
 

docs/src/api/PowerSimulations.md

@@ -7,35 +7,10 @@ end
 
 # API Reference
 
-## Table of Contents
-
-* [Device Models](#Device-Models)
-    * [Formulations](#Formulations)
-    * [Problem Templates](#Problem-Templates)
-* [Decision Models](#Decision-Models)
-* [Emulation Models](#Emulation-Models)
-* [Service Models](#Service-Models)
-* [Simulation Models](#Simulation-Models)
-* [Variables](#Variables)
-    * [Common Variables](#Common-Variables)
-    * [Thermal Unit Variables](#Thermal-Unit-Variables)
-    * [Storage Unit Variables](#Storage-Unit-Variables)
-    * [Branches and Network Variables](#Branches-and-Network-Variables)
-    * [Services Variables](#Services-Variables)
-    * [Feedforward Variables](#Feedforward-Variables)
-* [Constraints](#Constraints)
-    * [Common Constraints](#Common-Constraints)
-    * [Network Constraints](#Network-Constraints)
-    * [Power Variable Limit Constraints](#Power-Variable-Limit-Constraints)
-    * [Services Constraints](#Services-Constraints)
-    * [Thermal Unit Constraints](#Thermal-Unit-Constraints)
-    * [Renewable Unit Constraints](#Renewable-Unit-Constraints)
-    * [Branches Constraints](#Branches-Constraints)
-    * [Feedforward Constraints](#Feedforward-Constraints)
-* [Parameters](#Parameters)
-    * [Time Series Parameters](#Time-Series-Parameters)
-    * [Variable Value Parameters](#Variable-Value-Parameters)
-    * [Objective Function Parameters](#Objective-Function-Parameters)
+```@contents
+Pages = ["PowerSimulations.md"]
+Depth = 3
+```
 
 ```@raw html
  
@@ -56,32 +31,40 @@ Refer to the [Formulations Page](@ref formulation_library) for each Abstract Dev
 
 ### Problem Templates
 
-Refer to the [Problem Templates Page](@ref op_problem_template) for available `ProblemTemplate`s.
-
+```@autodocs
+Modules = [PowerSimulations]
+Pages   = ["problem_template.jl",
+            "operation_problem_templates.jl",
+           ]
+Order = [:type, :function]
+Public = true
+Private = false
+```
 
 ```@raw html
  
  
 ```
 
----
+* * *
 
 ## Decision Models
 
-```@docs
-DecisionModel
-DecisionModel(::Type{M} where {M <: DecisionProblem}, ::ProblemTemplate, ::PSY.System, ::Union{Nothing, JuMP.Model})
-DecisionModel(::AbstractString, ::MOI.OptimizerWithAttributes)
-build!(::DecisionModel)
-solve!(::DecisionModel)
+```@autodocs
+Modules = [PowerSimulations]
+Pages   = ["decision_model.jl",
+           ]
+Order = [:type, :function]
+Public = true
+Private = false
 ```
 
 ```@raw html
 &nbsp;
 &nbsp;
 ```
 
----
+* * *
 
 ## Emulation Models
 
@@ -91,14 +74,15 @@ EmulationModel(::Type{M} where {M <: EmulationProblem}, ::ProblemTemplate, ::PSY
 EmulationModel(::AbstractString, ::MOI.OptimizerWithAttributes)
 build!(::EmulationModel)
 run!(::EmulationModel)
+solve!(::Int, ::EmulationModel{<:EmulationProblem}, ::Dates.DateTime, ::SimulationStore)
 ```
 
 ```@raw html
 &nbsp;
 &nbsp;
 ```
 
----
+* * *
 
 ## Service Models
 
@@ -113,13 +97,14 @@ ServiceModel
 &nbsp;
 ```
 
----
+* * *
 
 ## Simulation Models
 
 Refer to the [Simulations Page](@ref running_a_simulation) to explanations on how to setup a Simulation, with Sequencing and Feedforwards.
 
 ```@docs
+InitialCondition
 SimulationModels
 SimulationSequence
 Simulation
@@ -128,16 +113,37 @@ build!(::Simulation)
 execute!(::Simulation)
 ```
 
+```@autodocs
+Modules = [PowerSimulations]
+Pages   = ["simulation_partitions.jl",
+           ]
+Order = [:type, :function]
+Public = true
+Private = false
+```
+
 ```@raw html
 &nbsp;
 &nbsp;
 ```
 
----
+## Chronology Models
 
-# Variables
+```@autodocs
+Modules = [PowerSimulations]
+Pages   = ["initial_condition_chronologies.jl",
+           ]
+Order = [:type, :function]
+Public = true
+Private = false
+```
+
+* * *
+
+## Variables
 
 For a list of variables for each device refer to its Formulations page.
+
 ### Common Variables
 
 ```@docs
@@ -165,6 +171,9 @@ PowerOutput
 
 ```@docs
 ReservationVariable
+EnergyVariable
+ActivePowerOutVariable
+ActivePowerInVariable
 ```
 
 ### Branches and Network Variables
@@ -208,7 +217,7 @@ LowerBoundFeedForwardSlack
 &nbsp;
 ```
 
----
+* * *
 
 ## Constraints
 
@@ -225,6 +234,7 @@ PieceWiseLinearCostConstraint
 CopperPlateBalanceConstraint
 NodalBalanceActiveConstraint
 NodalBalanceReactiveConstraint
+AreaParticipationAssignmentConstraint
 ```
 
 ### Power Variable Limit Constraints
@@ -289,7 +299,7 @@ FeedforwardLowerBoundConstraint
 &nbsp;
 ```
 
----
+* * *
 
 ## Parameters
 
@@ -315,3 +325,53 @@ FixValueParameter
 ```@docs
 CostFunctionParameter
 ```
+
+## Results
+
+### Acessing Optimization Model
+
+```@autodocs
+Modules = [PowerSimulations]
+Pages   = ["optimization_container.jl",
+            "optimization_debugging.jl"
+           ]
+Order = [:type, :function]
+Public = true
+Private = false
+```
+
+### Accessing Problem Results
+
+```@autodocs
+Modules = [PowerSimulations]
+Pages   = ["operation/problem_results.jl",
+           ]
+Order = [:type, :function]
+Public = true
+Private = false
+```
+
+### Accessing Simulation Results
+
+```@autodocs
+Modules = [PowerSimulations]
+Pages   = ["simulation_results.jl",
+            "simulation_problem_results.jl",
+            "simulation_partition_results.jl",
+            "hdf_simulation_store.jl"
+           ]
+Order = [:type, :function]
+Public = true
+Private = false
+```
+
+## Simulation Recorder
+
+```@autodocs
+Modules = [PowerSimulations]
+Pages   = ["utils/recorder_events.jl",
+           ]
+Order = [:type, :function]
+Public = true
+Private = false
+```

docs/src/code_base_developer_guide/developer.md

@@ -4,8 +4,8 @@ In order to contribute to `PowerSystems.jl` repository please read the following
 [`InfrastructureSystems.jl`](https://github.com/NREL-Sienna/InfrastructureSystems.jl)
 documentation in detail:
 
-1. [Style Guide](https://nrel-Sienna.github.io/InfrastructureSystems.jl/stable/style/)
-2. [Contributing Guidelines](https://github.com/NREL-Sienna/PowerSystems.jl/blob/main/CONTRIBUTING.md)
+ 1. [Style Guide](https://nrel-Sienna.github.io/InfrastructureSystems.jl/stable/style/)
+ 2. [Contributing Guidelines](https://github.com/NREL-Sienna/PowerSystems.jl/blob/main/CONTRIBUTING.md)
 
 Pull requests are always welcome to fix bugs or add additional modeling capabilities.
 

docs/src/code_base_developer_guide/internal.md

@@ -0,0 +1,10 @@
+```@meta
+CollapsedDocStrings = true
+```
+
+# Internal API
+
+```@autodocs
+Modules = [PowerSimulations]
+Public = false
+```