Jb/documentation updates by jbrossman · Pull Request #1635 · NREL-Sienna/PowerSystems.jl

jbrossman · 2026-02-24T21:09:24Z

Draft PR to address issues shown in #1504 and #1461 . Most changes occur from the supplemental attributes and system explanations. Spelling and cross reference issues were also addressed. While compiling the documentation a lot of the files were changed, but it's not clear what the change was.

One known issue still which is a figure not displaying. I will continue to work on this.

The contributing guidelines opened a link that did not work for me as well. Not sure if that is because I am a NLR employee or if the link is broken.

…per_unit explanation for transformers

Changed accessor and getter language across multiple pages

Edits include deleting the original supplemental attributes explanation, and creating a new one. Then, adding in two how tos, which describe how to add supplemental attributes and then a second how to about querying the supplemental attributes to get additional information. Update the glossary with UUID description as well.

First edits to system explanation and a new how-to. Also edited the make.jl file to include previously committed files and these new files.

@id

Key changes include adding @id references to the tutorials, referencing those tutorials in the explanation, and creating a separate how-to using code originally featured in the system explanation.

Successfully compiled the documentation and fixed a number of issues. Most of them were for broken or missing references.

codecov · 2026-02-24T22:46:51Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.05%. Comparing base (1617cc3) to head (0224c49).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1635      +/-   ##
==========================================
+ Coverage   84.03%   84.05%   +0.01%     
==========================================
  Files         203      203              
  Lines       10462    10462              
==========================================
+ Hits         8792     8794       +2     
+ Misses       1670     1668       -2

Flag	Coverage Δ
unittests	`84.05% <ø> (+0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

kdayday · 2026-02-25T00:16:13Z

@jbrossman I haven't taken a look yet, but FYI, about figures there's a different file path to get it to show up locally versus on github ("../" vs. "../../" or vice versa). We will want whichever one gets it to show up on the github Preview, so don't worry about it if it doesn't show up locally

github-actions · 2026-03-02T21:11:24Z

docs/src/explanation/type_structure.md

+1. **Categorization by behavior:** Components that serve the same modeling role share a
+   common abstract supertype. Code can retrieve all components of a given category — all
+   generators, all transmission branches — without enumerating every specific technology
+   type.
+
+2. **Generic and extensible model logic:** Downstream packages such as
+   [`PowerSimulations.jl`](https://nrel-sienna.github.io/PowerSimulations.jl/stable/)
+   define optimization formulations against abstract types. A new concrete component type
+   slots into existing model formulations automatically, as long as it implements the
+   expected interface. This means users can define technologies not yet in the package and
+   have them work with existing tools.


[JuliaFormatter] _{reported by reviewdog 🐶}

Suggested change

1. **Categorization by behavior:** Components that serve the same modeling role share a

common abstract supertype. Code can retrieve all components of a given category — all

generators, all transmission branches — without enumerating every specific technology

type.

2. **Generic and extensible model logic:** Downstream packages such as

[`PowerSimulations.jl`](https://nrel-sienna.github.io/PowerSimulations.jl/stable/)

define optimization formulations against abstract types. A new concrete component type

slots into existing model formulations automatically, as long as it implements the

expected interface. This means users can define technologies not yet in the package and

have them work with existing tools.

1. **Categorization by behavior:** Components that serve the same modeling role share a

common abstract supertype. Code can retrieve all components of a given category — all

generators, all transmission branches — without enumerating every specific technology

type.

2. **Generic and extensible model logic:** Downstream packages such as

[`PowerSimulations.jl`](https://nrel-sienna.github.io/PowerSimulations.jl/stable/)

define optimization formulations against abstract types. A new concrete component type

slots into existing model formulations automatically, as long as it implements the

expected interface. This means users can define technologies not yet in the package and

have them work with existing tools.

github-actions · 2026-03-02T21:11:24Z

docs/src/explanation/type_structure.md

-``` ⠀
+For a hands-on introduction to navigating the type hierarchy, see the
+[Create and Explore a Power System](@ref tutorial_creating_system) tutorial.
 ```


[JuliaFormatter] _{reported by reviewdog 🐶}

Suggested change

```

```

```

kdayday · 2026-03-03T01:17:26Z

docs/src/tutorials/creating_system.jl

@@ -1,4 +1,4 @@
-# # Create and Explore a Power `System`
+# # [Create and Explore a Power `System`](@id tutorial_creating_system)


I think these ID tags show up badly in the Jupyter notebook versions of the tutorials, so let's remove and just use the title tags if it all possible

docs/src/explanation/supplemental_attributes_2.md

kdayday · 2026-03-03T01:25:40Z

docs/src/how_to/use_subsystems.md

+    The system above is invalid because the bus connected to the Alta generator is not
+    part of subsystem "1". Add the bus first, then re-run [`from_subsystem`](@ref):
+
+```@repl subsystem


This doesn't fully get to an error-free resolution. Maybe at least make a comment underneath that a similar approach would be needed to resolve the remaining errors ( adding a slack bus or modifying the existing bus, adding an electric load to the subsystem)

kdayday · 2026-03-03T01:30:09Z

docs/src/explanation/type_structure.md

@@ -1,12 +1,35 @@
 # [Type Structure](@id type_structure)


kdayday · 2026-03-03T01:31:08Z

docs/src/explanation/type_structure.md

+
+Each infrastructure component is represented as a [`struct`](@ref S) — a composite data
+type that bundles together the fields needed to describe that component. For example, an
+`ACBus` carries fields for its bus number, nominal voltage, bus type, and more:


Add hyperlinks on all type and function names

Jes Brossman added 9 commits February 17, 2026 15:17

Additional changes to supplemental attributes and initial changes to …

bcba6ba

…per_unit explanation for transformers

Update figure size

828910d

Add to glossary and fix spelling mistakes

db59c76

Additional spelling edits

6ee4e64

Changed accessor to getter functions

5ae3d74

Changed accessor and getter language across multiple pages

First pass at edits to system

cede0fb

First edits to system explanation and a new how-to. Also edited the make.jl file to include previously committed files and these new files.

Finish system explanation edits

386116e

Key changes include adding @id references to the tutorials, referencing those tutorials in the explanation, and creating a separate how-to using code originally featured in the system explanation.

Ran compilation and fixed mostly reference issues

0d81648

Successfully compiled the documentation and fixed a number of issues. Most of them were for broken or missing references.

jbrossman requested a review from kdayday February 24, 2026 21:09

jbrossman self-assigned this Feb 24, 2026

jbrossman added the documentation label Feb 24, 2026

Edits to Type Structure Explanation

f921449

github-actions bot reviewed Mar 2, 2026

View reviewed changes

Edits to buses_type_explanation.md

0224c49

kdayday reviewed Mar 3, 2026

View reviewed changes

docs/src/explanation/supplemental_attributes_2.md Show resolved Hide resolved

kdayday reviewed Mar 3, 2026

View reviewed changes

docs/src/explanation/supplemental_attributes_2.md Show resolved Hide resolved

kdayday reviewed Mar 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Jb/documentation updates#1635

Jb/documentation updates#1635
jbrossman wants to merge 11 commits intomainfrom
jb/documentation-updates

jbrossman commented Feb 24, 2026

Uh oh!

codecov bot commented Feb 24, 2026 •

edited

Loading

Uh oh!

kdayday commented Feb 25, 2026

Uh oh!

github-actions bot Mar 2, 2026

Uh oh!

github-actions bot Mar 2, 2026

Uh oh!

kdayday Mar 3, 2026

Uh oh!

Uh oh!

Uh oh!

kdayday Mar 3, 2026

Uh oh!

kdayday Mar 3, 2026

Uh oh!

kdayday Mar 3, 2026

Uh oh!

kdayday Mar 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

-```
+```
+```

		@@ -1,4 +1,4 @@
		# # Create and Explore a Power `System`
		# # [Create and Explore a Power `System`](@id tutorial_creating_system)

Conversation

jbrossman commented Feb 24, 2026

Uh oh!

codecov bot commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

kdayday commented Feb 25, 2026

Uh oh!

github-actions bot Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

kdayday Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

kdayday Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

kdayday Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

kdayday Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

kdayday Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov bot commented Feb 24, 2026 •

edited

Loading