Merge pull request #1176 from kdayday/docs_cleanup

Documentation clean up, update to Documenter 1.0, add *.md to formatter (PSY portion)
NREL-Sienna · Sep 23, 2024 · 4e270f3 · 4e270f3
2 parents 985bdd5 + ba1a44d
commit 4e270f3
Show file tree

Hide file tree

Showing 67 changed files with 2,269 additions and 1,649 deletions.
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -15,6 +15,6 @@ TypeTree = "04da0e3b-1cad-4b2c-a963-fc1602baf1af"
 
 [compat]
 CSV = "~0.10"
-Documenter = "^0.27"
+Documenter = "^1.5"
 InfrastructureSystems = "2"
 julia = "^1.6"
diff --git a/docs/make.jl b/docs/make.jl
@@ -12,22 +12,24 @@ pages = OrderedDict(
         "Tutorials" =>  Any[
             "Create and Explore a Power `System`" => "tutorials/creating_system.md",
             "Working with Time Series" => "tutorials/working_with_time_series.md",
-            "Adding dynamic devices" => "tutorials/add_dynamic_device.md",
+            "Adding Data for Dynamic Simulations" => "tutorials/add_dynamic_data.md",
         ],
         "How to..." =>  Any[
             "...install PowerSystems.jl" => "how_to/install.md",
             "...load a `system` from `PowerSystemCaseBuilder`" => "how_to/powersystembuilder.md",
-            "...parse data from Matpower, PSSE, or CSV files" => "how_to/parsing.md",
-            "...add time series data from CSVs" => "how_to/add_ts_from_csvs.md",
-            "...customize the tabular data parser" => "how_to/extend_tabular_parsing.md",
+            "...parse data from MATPOWER or PSS/e files" => "how_to/parse_matpower_psse.md",
+            "...parse PSS/e dynamic data" => "how_to/parse_dynamic_data.md",
+            "...parse tabular data from .csv files" => "how_to/parse_tabular_data.md",
+            "...parse time series data from .csv files" => "how_to/parse_ts_from_csvs.md",
+            "...add a component using natural units (MW)" => "how_to/add_component_natural_units.md",
             "...get all the buses in a system" => "how_to/get_buses.md",
             "...get the available generators in a system" => "how_to/get_available_generators.md",
             "...add an Operating Cost" => "how_to/add_cost_curve.md",
             "...add a market bid" => "how_to/market_bid_cost.md",
             "...add additional data to a component" => "how_to/adding_additional_fields.md",
-            "...add a new Type" => "how_to/add_new_types.md",
+            "...customize or add a new Type" => "how_to/add_new_types.md",
             "...improve performance with time series data" => "how_to/improve_ts_performance.md",
-            "...serialize data to a JSON" => "how_to/serialize_data.md",
+            "...write and read data with a JSON" => "how_to/serialize_data.md",
             "...reduce REPL printing" => "how_to/reduce_repl_printing.md",
             "...migrate from version 3.0 to 4.0" => "how_to/migrating_to_psy4.md"
         ],
@@ -37,18 +39,18 @@ pages = OrderedDict(
             "explanation/type_structure.md",
             "explanation/per_unit.md",
             "explanation/time_series.md",
-            "explanation/example_dynamic_data.md",
+            "explanation/dynamic_data.md",
             ],
         "Model Library" => Any[],
         "Reference" =>
             Any["Public API" => "api/public.md",
-            "Internal API Reference" => "api/internal.md",
             "Glossary and Acronyms" => "api/glossary.md",
             "Type Hierarchy" => "api/type_tree.md",
             "`ValueCurve` Options" => "api/valuecurve_options.md",
             "Specifying the category of..." => "api/enumerated_types.md",
-            "Developer Guidelines" => "api/developer_guidelines.md",
-            "Citation" => "api/citation.md"
+            "Citation" => "api/citation.md",
+            "Developers" => ["Developer Guidelines" => "api/developer_guidelines.md",
+            "Internals" => "api/internal.md"]
             ]
 
 
@@ -59,14 +61,17 @@ pages["Model Library"] = make_model_library(
         Topology,
         StaticInjection,
         Service,
-        Branch
+        Branch,
+        DynamicInjection,
     ],
     exceptions = [PSY.DynamicComponent,
                   PSY.ActivePowerControl,
                   PSY.ReactivePowerControl,
                   PSY.DynamicBranch,
                   PSY.HybridSystem,
-                  PSY.OperationalCost
+                  PSY.OperationalCost,
+                  PSY.DynamicInverter,
+                  PSY.DynamicGenerator,
                   ],
     manual_additions =
         Dict("Service" => ["Reserves" => "model_library/reserves.md"],
@@ -81,8 +86,6 @@ pages["Model Library"] = make_model_library(
         "StorageCost" =>"model_library/storage_cost.md",
         "LoadCost" =>"model_library/load_cost.md",
         "MarketBidCost" =>"model_library/market_bid_cost.md"],
-        "Cost Curves" => ["Variable Cost Curves" => "model_library/cost_curves.md",
-        "Value Curves" => "model_library/value_curves.md"]
         )
 )
 
@@ -128,11 +131,14 @@ for (section, folder) in folders
 end
 
 makedocs(
-    modules = [PowerSystems, InfrastructureSystems],
-    format = Documenter.HTML(prettyurls = haskey(ENV, "GITHUB_ACTIONS"),),
+    modules = [PowerSystems],
+    format = Documenter.HTML(
+        prettyurls = haskey(ENV, "GITHUB_ACTIONS"),
+        size_threshold = nothing,),
     sitename = "PowerSystems.jl",
-    authors = "Jose Daniel Lara, Daniel Thom, Kate Doubleday, and Clayton Barrows",
-    pages = Any[p for p in pages]
+    authors = "Jose Daniel Lara, Daniel Thom, Kate Doubleday, Rodrigo Henriquez-Auba, and Clayton Barrows",
+    pages = Any[p for p in pages],
+    draft = false,
 )
 
 deploydocs(

diff --git a/docs/src/api/citation.md b/docs/src/api/citation.md
@@ -17,7 +17,6 @@ author = {José Daniel Lara and Clayton Barrows and Daniel Thom and Dheepak Kris
 keywords = {Power Systems, Julia, Energy},
 ```
 
-------------
-PowerSystems has been developed as part of the [Sienna modeling framework](https://www.nrel.gov/analysis/sienna.html)
+PowerSystems has been developed as part of the [Sienna platform](https://www.nrel.gov/analysis/sienna.html)
 by the U.S. Department of Energy's National Renewable Energy Laboratory
 ([NREL](https://www.nrel.gov/)).
diff --git a/docs/src/api/developer_guidelines.md b/docs/src/api/developer_guidelines.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.
 

diff --git a/docs/src/api/enumerated_types.md b/docs/src/api/enumerated_types.md
@@ -1,10 +1,10 @@
-
 # Specifying the type of...
 
 Some fields in PowerSystems.jl are specified with an option from a pre-defined list
-(Specified with [`IS.scoped_enums`](https://nrel-sienna.github.io/InfrastructureSystems.jl/stable/InfrastructureSystems/#InfrastructureSystems.@scoped_enum-Tuple{Any,%20Vararg{Any,%20N}%20where%20N})).
+(Specified with [`IS.scoped_enums`](https://nrel-sienna.github.io/InfrastructureSystems.jl/stable/InfrastructureSystems/#InfrastructureSystems.@scoped_enum-Tuple%7BAny,%20Vararg%7BAny,%20N%7D%20where%20N%7D)).
 
 Example syntax:
+
 ```
 set_fuel!(gen, ThermalFuels.COAL)
 ```
@@ -16,45 +16,45 @@ These predefined lists are below:
 `ACBusTypes` categorize buses for modeling activities and denote which quantities are specified
 for load flow calculations. `ACBusTypes` has the options:
 
-| Name | Description |
-|:----------|:-------------|
-| `ISOLATED` | Disconnected from network |
-| `PQ` | Active and reactive power defined (load bus)|
-| `PV` | Active power and voltage magnitude defined (generator bus)|
-| `REF` | Reference bus (θ = 0)|
-| `SLACK` | Slack bus |
+| Name       | Description                                                |
+|:---------- |:---------------------------------------------------------- |
+| `ISOLATED` | Disconnected from network                                  |
+| `PQ`       | Active and reactive power defined (load bus)               |
+| `PV`       | Active power and voltage magnitude defined (generator bus) |
+| `REF`      | Reference bus (θ = 0)                                      |
+| `SLACK`    | Slack bus                                                  |
 
 ## [Prime Movers](@id pm_list)
 
 Each generator contains a field for `prime_mover::PrimeMovers`, based on the options in
 [EIA form 923](https://www.eia.gov/survey/form/eia_923/instructions.pdf).
 `PrimeMovers` has the options:
 
-| Name | Description |
-|:----------|:-------------|
-| `BA` | Energy Storage, Battery |
-| `BT` | Turbines Used in a Binary Cycle (including those used for geothermal applications) |
-| `CA` | Combined-Cycle – Steam Part |
-| `CC` | Combined-Cycle - Aggregated Plant *augmentation of EIA |
-| `CE` | Energy Storage, Compressed Air |
-| `CP` | Energy Storage, Concentrated Solar Power |
-| `CS` | Combined-Cycle Single-Shaft Combustion turbine and steam turbine share a single generator |
-| `CT` | Combined-Cycle Combustion Turbine Part |
-| `ES` | Energy Storage, Other |
-| `FC` | Fuel Cell |
-| `FW` | Energy Storage, Flywheel |
-| `GT` | Combustion (Gas) Turbine (including jet engine design) |
-| `HA` | Hydrokinetic, Axial Flow Turbine |
-| `HB` | Hydrokinetic, Wave Buoy |
-| `HK` | Hydrokinetic, Other |
-| `HY` | Hydraulic Turbine (including turbines associated with delivery of water by pipeline) |
-| `IC` | Internal Combustion (diesel, piston, reciprocating) Engine |
-| `PS` | Energy Storage, Reversible Hydraulic Turbine (Pumped Storage) |
-| `OT` | Other |
-| `ST` | Steam Turbine (including nuclear, geothermal and solar steam; does not include combined-cycle turbine) |
-| `PVe` | Photovoltaic \(*Note*: renaming from EIA PV to PVe to avoid conflict with `ACBusType.PV`\) |
-| `WT` | Wind Turbine, Onshore |
-| `WS` | Wind Turbine, Offshore |
+| Name  | Description                                                                                            |
+|:----- |:------------------------------------------------------------------------------------------------------ |
+| `BA`  | Energy Storage, Battery                                                                                |
+| `BT`  | Turbines Used in a Binary Cycle (including those used for geothermal applications)                     |
+| `CA`  | Combined-Cycle – Steam Part                                                                            |
+| `CC`  | Combined-Cycle - Aggregated Plant *augmentation of EIA                                                 |
+| `CE`  | Energy Storage, Compressed Air                                                                         |
+| `CP`  | Energy Storage, Concentrated Solar Power                                                               |
+| `CS`  | Combined-Cycle Single-Shaft Combustion turbine and steam turbine share a single generator              |
+| `CT`  | Combined-Cycle Combustion Turbine Part                                                                 |
+| `ES`  | Energy Storage, Other                                                                                  |
+| `FC`  | Fuel Cell                                                                                              |
+| `FW`  | Energy Storage, Flywheel                                                                               |
+| `GT`  | Combustion (Gas) Turbine (including jet engine design)                                                 |
+| `HA`  | Hydrokinetic, Axial Flow Turbine                                                                       |
+| `HB`  | Hydrokinetic, Wave Buoy                                                                                |
+| `HK`  | Hydrokinetic, Other                                                                                    |
+| `HY`  | Hydraulic Turbine (including turbines associated with delivery of water by pipeline)                   |
+| `IC`  | Internal Combustion (diesel, piston, reciprocating) Engine                                             |
+| `PS`  | Energy Storage, Reversible Hydraulic Turbine (Pumped Storage)                                          |
+| `OT`  | Other                                                                                                  |
+| `ST`  | Steam Turbine (including nuclear, geothermal and solar steam; does not include combined-cycle turbine) |
+| `PVe` | Photovoltaic \(*Note*: renaming from EIA PV to PVe to avoid conflict with `ACBusType.PV`\)             |
+| `WT`  | Wind Turbine, Onshore                                                                                  |
+| `WS`  | Wind Turbine, Offshore                                                                                 |
 
 ## [Fuels for Thermal Generators](@id tf_list)
 
@@ -63,60 +63,60 @@ are intended to reflect the options in the
 [Aggregated Fuel Codes](https://www.eia.gov/survey/form/eia_923/instructions.pdf) from the
 EIA Annual Energy Review. `ThermalFuels` has the options:
 
-| Name | EIA Fuel Code | Description |
-|:----------|:---------------|:-------------|
-| `COAL` | COL | Anthracite Coal and Bituminous Coal |
-| `WASTE_COAL` | WOC | Waste/Other Coal (includes anthracite culm, gob, fine coal, lignite waste, waste coal) |
-| `DISTILLATE_FUEL_OIL` | DFO | Distillate Fuel Oil (Diesel, No. 1, No. 2, and No. 4) |
-| `WASTE_OIL` | WOO | Waste Oil Kerosene and JetFuel Butane, Propane |
-| `PETROLEUM_COKE` | PC | Petroleum Coke |
-| `RESIDUAL_FUEL_OIL` | RFO | Residual Fuel Oil (No. 5, No. 6 Fuel Oils, and Bunker Oil) |
-| `NATURAL_GAS` | NG | Natural Gas |
-| `OTHER_GAS` | OOG | Other Gas and blast furnace gas |
-| `NUCLEAR` | NUC | Nuclear Fission (Uranium, Plutonium, Thorium) |
-| `AG_BIPRODUCT` | ORW | Agricultural Crop Byproducts/Straw/Energy Crops |
-| `MUNICIPAL_WASTE` |  MLG | Municipal Solid Waste – Biogenic component |
-| `WOOD_WASTE` | WWW | Wood Waste Liquids excluding Black Liquor (BLQ) (Includes red liquor, sludge wood, spent sulfite liquor, and other wood-based liquids) |
-| `GEOTHERMAL` | GEO | Geothermal |
-| `OTHER` | OTH | Other |
+| Name                  | EIA Fuel Code | Description                                                                                                                            |
+|:--------------------- |:------------- |:-------------------------------------------------------------------------------------------------------------------------------------- |
+| `COAL`                | COL           | Anthracite Coal and Bituminous Coal                                                                                                    |
+| `WASTE_COAL`          | WOC           | Waste/Other Coal (includes anthracite culm, gob, fine coal, lignite waste, waste coal)                                                 |
+| `DISTILLATE_FUEL_OIL` | DFO           | Distillate Fuel Oil (Diesel, No. 1, No. 2, and No. 4)                                                                                  |
+| `WASTE_OIL`           | WOO           | Waste Oil Kerosene and JetFuel Butane, Propane                                                                                         |
+| `PETROLEUM_COKE`      | PC            | Petroleum Coke                                                                                                                         |
+| `RESIDUAL_FUEL_OIL`   | RFO           | Residual Fuel Oil (No. 5, No. 6 Fuel Oils, and Bunker Oil)                                                                             |
+| `NATURAL_GAS`         | NG            | Natural Gas                                                                                                                            |
+| `OTHER_GAS`           | OOG           | Other Gas and blast furnace gas                                                                                                        |
+| `NUCLEAR`             | NUC           | Nuclear Fission (Uranium, Plutonium, Thorium)                                                                                          |
+| `AG_BIPRODUCT`        | ORW           | Agricultural Crop Byproducts/Straw/Energy Crops                                                                                        |
+| `MUNICIPAL_WASTE`     | MLG           | Municipal Solid Waste – Biogenic component                                                                                             |
+| `WOOD_WASTE`          | WWW           | Wood Waste Liquids excluding Black Liquor (BLQ) (Includes red liquor, sludge wood, spent sulfite liquor, and other wood-based liquids) |
+| `GEOTHERMAL`          | GEO           | Geothermal                                                                                                                             |
+| `OTHER`               | OTH           | Other                                                                                                                                  |
 
 ## [Energy Storage](@id storagetech_list)
 
 `StorageTech` defines the storage technology used in an energy [`Storage`](@ref) system, based
 on the options in [EIA form 923](https://www.eia.gov/survey/form/eia_923/instructions.pdf).
 `StorageTech` has the options:
 
-| Name | Description |
-|:----------|:-------------|
-| `PTES` | Pumped thermal energy storage |
-| `LIB` | LiON Battery |
-| `LAB` | Lead Acid Battery |
-| `FLWB` | Redox Flow Battery |
-| `SIB` | Sodium Ion Battery |
-| `ZIB` | Zinc Ion Battery |
-| `HGS` | Hydrogen Gas Storage |
-| `LAES` | Liquid Air Storage |
-| `OTHER_CHEM` | Other Chemical Storage |
-| `OTHER_MECH` | Other Mechanical Storage |
-| `OTHER_THERM` | Other Thermal Storage |
+| Name          | Description                   |
+|:------------- |:----------------------------- |
+| `PTES`        | Pumped thermal energy storage |
+| `LIB`         | LiON Battery                  |
+| `LAB`         | Lead Acid Battery             |
+| `FLWB`        | Redox Flow Battery            |
+| `SIB`         | Sodium Ion Battery            |
+| `ZIB`         | Zinc Ion Battery              |
+| `HGS`         | Hydrogen Gas Storage          |
+| `LAES`        | Liquid Air Storage            |
+| `OTHER_CHEM`  | Other Chemical Storage        |
+| `OTHER_MECH`  | Other Mechanical Storage      |
+| `OTHER_THERM` | Other Thermal Storage         |
 
 ## [Dynamic States](@id states_list)
 
 `StateTypes` are used to denote the type of dynamic equation a specific [state](@ref S) is subject
 to in [`PowerSimulationsDynamics.jl`](https://nrel-sienna.github.io/PowerSimulationsDynamics.jl/stable/).
 `StateTypes` has the options:
 
-| Name | Description |
-|:----------|:-------------|
-| `Differential` | State evolves over time via a differential equation ``\dot{x} = f(x)`` |
-| `Algebraic` | State evolves over time by satisfying an algebraic equation ``0 = g(x)`` |
-| `Hybrid` | Depending on specific parameters, the state can be `Differential` or `Algebraic` |
+| Name           | Description                                                                      |
+|:-------------- |:-------------------------------------------------------------------------------- |
+| `Differential` | State evolves over time via a differential equation ``\dot{x} = f(x)``           |
+| `Algebraic`    | State evolves over time by satisfying an algebraic equation ``0 = g(x)``         |
+| `Hybrid`       | Depending on specific parameters, the state can be `Differential` or `Algebraic` |
 
 ## [Angle Units](@id angleunits_list)
 
 `AngleUnits` can be specified in:
 
-| Name |
-|----------|
+| Name      |
+|:--------- |
 | `DEGREES` |
-| `RADIANS` |
+| `RADIANS` |