Run formatter

docs/src/docs_best_practices/how-to/compile.md

@@ -1,29 +1,32 @@
 # Compile and View Documentation Locally
 
 ## Step 0a: Update Docs Environment (First Time)
+
 The first time you compile documentation for a package, make sure the `docs/` environment
 (i.e., `docs/Manifest.toml`, not the main `Manifest.toml` in the root of the repository)
 is pointing to your local version of the package, so it compiles your local changes:
 
-```julia
+```
 julia --project=docs
 using Pkg
 Pkg.develop(path = "..")
 ```
 
 ## Step 0b: Auto-Generate Structs (If Needed)
+
 Most documentation changes are made directly to markdown (.md) files, but if you changed one
 of Sienna's .json descriptor files, you must first
 [follow the instructions here](@ref "Auto-Generation of Component Structs") to auto-generate
 the structs from the .json to have your changes propagated into the markdown files used for
-documentation. 
+documentation.
 
 **Example**: You updated `PowerSystems.jl`'
 [`power_system_structs.json`](https://github.com/NREL-Sienna/PowerSystems.jl/blob/main/src/descriptors/power_system_structs.json)
 file.
 
 From a terminal at the root of the repository (i.e., `PowerSystems.jl`), run:
-```julia
+
+```
 julia --project=.
 using InfrastructureSystems
 InfrastructureSystems.generate_structs(
@@ -33,8 +36,10 @@ InfrastructureSystems.generate_structs(
 ```
 
 ## Step 0c: Run the Formatter (Before Submitting a Pull Request)
+
 To automatically format the documentation to conform with the [style guide](@ref style_guide),
 run in a terminal at the root of the repository:
+
 ```
 julia scripts/formatter/formatter_code.jl
 ```
@@ -43,11 +48,12 @@ Resolve any errors and re-run until error-free. See how to [Troubleshoot Common
 for help.
 
 This is not a necessary step to compile, but needs to be done at least once to pass pull
-request checks. 
+request checks.
 
 ## Step 1: Compile
 
 To compile, run in a terminal at the root of the repository:
+
 ```
 julia --project=docs docs/make.jl 
 ```
@@ -56,8 +62,9 @@ Resolve any errors and re-run until error-free. See how to [Troubleshoot Common
 for help.
 
 ## Step 2: View
+
 Click on the newly-created `index.html` file (e.g.,
 `SomeSiennaPackage/docs/build/index.html`) to view your locally compiled documentation in a
-browser. 
+browser.
 
 Visually verify formatting and that code blocks compile as expected.

docs/src/docs_best_practices/how-to/general_formatting.md

@@ -1,4 +1,4 @@
-# Clean Up General Formatting 
+# Clean Up General Formatting
 
 These recommendations are to make navigating our documentation effortless for users, while
 addressing common markdown formatting issues in the existing Sienna documentation:
@@ -7,28 +7,39 @@ addressing common markdown formatting issues in the existing Sienna documentatio
 
 All package names, types, functions, methods, and parameters, etc. should formatted in
 back-ticks:
+
 !!! tip "Do"
+
     ```
     `max_active_power`
     ```
+
     compiles as `max_active_power`
-!!! warning "Don't" 
+
+!!! warning "Don't"
+
     ```
     max_active_power
     ```
+
     compiles as max_active_power
 
 ## [Put hyperlinks everywhere](@id hyperlinks)
+
 All types, function, and methods should have hyperlinks to the correct docstring, accounting
 for multiple methods of the same name due to Julia's multiple dispatch.
 [`Documenter.jl`](https://documenter.juliadocs.org/stable/) will link to the first
 occurrance in documentation. If that's not the one you're referring to, copy the entire
 signature with types into the hyperlink reference.
+
 !!! tip "Do"
+
     ```
     [`get_time_series_values`](@ref)
     ```
+
     Or
+
     ```
     [`get_time_series_values` from a `ForecastCache`](@ref get_time_series_values(
     owner::TimeSeriesOwners,
@@ -38,29 +49,36 @@ signature with types into the hyperlink reference.
     ignore_scaling_factors = false,
     ))
     ```
-!!! warning "Don't" 
-    ```
-    `get_time_series_values`
-    ```
-    Or
-    ```
-    get_time_series_values
-    ```
+
+!!! warning "Don't"
+
+
+``get_time_series_values``
+Or
+`get_time_series_values`
 
 ## Add links to other Sienna packages
 
 All other Sienna package names should have documentation (not Git repo) hyperlinks:
+
 !!! tip "Do"
-    ``` [`PowerSystems.jl`](https://nrel-sienna.github.io/PowerSystems.jl/stable/) ```
-!!! warning "Don't" 
+
+    ```[`PowerSystems.jl`](https://nrel-sienna.github.io/PowerSystems.jl/stable/)```
+
+!!! warning "Don't"
+
     ```
     `PowerSystems.jl`
     ```
+
     Or
+
     ```
     PSY
     ```
+
     Or
+
     ```
     [`PowerSystems.jl`](https://github.com/NREL-Sienna/PowerSystems.jl)
     ```

docs/src/docs_best_practices/how-to/requirements_checklist.md

@@ -3,7 +3,7 @@
 Sienna packages should follow the [Diataxis](https://diataxis.fr/)
 framework, be strictly compiled with [`Documenter.jl`](https://documenter.juliadocs.org/stable/)
 v1.0 or greater, and be automatically formatted with
-[`JuliaFormatter.jl`](https://domluna.github.io/JuliaFormatter.jl/stable/). 
+[`JuliaFormatter.jl`](https://domluna.github.io/JuliaFormatter.jl/stable/).
 
 ## For New Packages
 
@@ -15,21 +15,24 @@ required environments and formatting and documentation code. Start from this tem
 Existing Sienna packages will need to be updated with these requirements, but these will
 only need to be addressed once:
 
-1. Organize the top-level documentation to follow the [Diataxis](https://diataxis.fr/)
+ 1. Organize the top-level documentation to follow the [Diataxis](https://diataxis.fr/)
     framework (plus a welcome page/section). This might be a significant undertaking. See:
-    - How to [Write a How-to Guide](@ref)
-    - How to [Write a Tutorial](@ref)
-    - How to [Organize APIs and Write Docstrings](@ref)
-1. Replace `compat` requirements of `Documenter = "0.27"` in `docs/` environment with
+
+      + How to [Write a How-to Guide](@ref)
+      + How to [Write a Tutorial](@ref)
+      + How to [Organize APIs and Write Docstrings](@ref)
+
+ 2. Replace `compat` requirements of `Documenter = "0.27"` in `docs/` environment with
     `Documenter = "1.0"`
-1. Update the `docs/make.jl` file to call
+ 3. Update the `docs/make.jl` file to call
     [`Documenter.makedocs`](https://documenter.juliadocs.org/stable/lib/public/#Documenter.makedocs)
     *without* the `warnonly` `kwarg` (i.e., all errors caught by `makedocs` must be resolved before
     merging). [See an example here](https://github.com/NREL-Sienna/InfrastructureSystems.jl/blob/768438a40c46767560891ec493cf87ed232a2b2b/docs/make.jl#L47).
-    - See How-to [Troubleshoot Common Errors](@ref) if this results in a host of errors. 
-1. Update the `scripts/formatter/formatter_code.jl` to format the markdown .md files in the
+
+      + See How-to [Troubleshoot Common Errors](@ref) if this results in a host of errors.
+ 4. Update the `scripts/formatter/formatter_code.jl` to format the markdown .md files in the
     `docs/` folder, calling `format`() with the `kwarg` `format_markdown = true`. See
     [these](https://github.com/NREL-Sienna/InfrastructureSystems.jl/blob/768438a40c46767560891ec493cf87ed232a2b2b/scripts/formatter/formatter_code.jl#L13)
     [three](https://github.com/NREL-Sienna/InfrastructureSystems.jl/blob/768438a40c46767560891ec493cf87ed232a2b2b/scripts/formatter/formatter_code.jl#L8)
     [links](https://github.com/NREL-Sienna/InfrastructureSystems.jl/blob/768438a40c46767560891ec493cf87ed232a2b2b/scripts/formatter/formatter_code.jl#L23)
-    for examples of the updated lines. 
+    for examples of the updated lines.

docs/src/docs_best_practices/how-to/view_github.md

@@ -1,6 +1,8 @@
 # View Draft Documentation on Github
 
-1. Create a pull request on Github.
-2. Verify the Documentation/build check was successful (takes a few minutes).
-2. Preview it in a browser following this url format:
-    > https://nrel-sienna.github.io/<PACKAGE\_NAME>.jl/previews/PR<PULL\_REQUEST\_NUMBER>/
+ 1. Create a pull request on Github.
+
+ 2. Verify the Documentation/build check was successful (takes a few minutes).
+ 3. Preview it in a browser following this url format:
+
+    > https://nrel-sienna.github.io/<PACKAGE\_NAME>.jl/previews/PR<PULL\_REQUEST\_NUMBER>/

docs/src/docs_best_practices/how-to/write_a_how-to.md

@@ -5,11 +5,11 @@ problem or series of linked problems.
 
 ## Prepare
 
-- If you have not read [Diataxis](https://diataxis.fr/), first read it in its entirety.
-- If you have read it, skim the pages on [How-to guides](https://diataxis.fr/how-to-guides/) and
+  - If you have not read [Diataxis](https://diataxis.fr/), first read it in its entirety.
+  - If you have read it, skim the pages on [How-to guides](https://diataxis.fr/how-to-guides/) and
     the [difference between a tutorial and how-to guide](https://diataxis.fr/tutorials-how-to/)
-    to refresh your memory and refer back throughout the process. 
-- Look at an example: this page, how to [Compile and View Documentation Locally](@ref), and
+    to refresh your memory and refer back throughout the process.
+  - Look at an example: this page, how to [Compile and View Documentation Locally](@ref), and
     how to [Troubleshoot Common Errors](@ref) are all examples.
 
 ## Follow the Do's and Don't's
@@ -25,53 +25,74 @@ Depth = 3:3
 ```
 
 ### Omit the Unnecessary
-!!! tip "Do"    
-    Jump the user right to a logical starting point in the code using `#hide` or
-    [`@setup`](https://documenter.juliadocs.org/stable/man/syntax/#reference-at-setup)
-    blocks.
+
+!!! tip "Do"
+
+
+Jump the user right to a logical starting point in the code using `#hide` or
+[`@setup`](https://documenter.juliadocs.org/stable/man/syntax/#reference-at-setup)
+blocks.
+
 !!! tip "Do"
+
     [Configure the logger](@ref log) or load/build a `System` that returns very
-        few log statements. Use semi-colons at line ends to hide return statements if need be.
+    few log statements. Use semi-colons at line ends to hide return statements if need be.
 
 ### Make it effortless to read
+
 !!! tip "Do"
+
     Split code examples into ideally 1 (to 3) lines ONLY, with a short preface
     to explain what each line is doing, even if it's obvious to you.
 
 ### Move Docstring Material to the APIs
+
 An issue with earlier versions of Sienna documentation was basic reference information
 located in pages other than the APIs.
 See how-to [Organize APIs and Write Docstrings](@ref) if needed to make that information
 easier to find.
+
 !!! tip "Do"
+
     Preface each call to a new function with a hyperlink to that function's
-        docstring so the user can find more detail
+    docstring so the user can find more detail
+
 !!! warning "Don't"
+
     Include digressive details about different keyword arguments or versions of
-        a function.
+    a function.
 
 ### Minimize or Eliminate How-To Guides with a Single Step
+
 A how-to guide has a *sequence* of steps -- if your guide only has a single step, ask
 yourself if you are compensating for a lack of information in the API's.
+
 !!! tip "Do"
+
     Move how-to guides with a single function to being Examples in that
     function's docstring. See [Writing Documentation](@extref).
 
 ### Remove Other Reference Material
+
 Particularly when editing existing pages, watch out for other
 [Reference](https://diataxis.fr/reference/) material.
+
 !!! tip "Do"
+
     Move tables and lists of information into Reference pages and link to them instead
 
 ### Follow the Guidelines on Cleaning Up General Formatting
 
 !!! tip "Do"
-    Follow How-to [Clean Up General Formatting](@ref). 
+
+    Follow How-to [Clean Up General Formatting](@ref).
 
 ### Look at the compiled .html!
+
 !!! tip "Do"
-    - [Compile](@ref "Compile and View Documentation Locally") the how-to guide regularly and
+
+      - [Compile](@ref "Compile and View Documentation Locally") the how-to guide regularly and
         look at it
-    - Check all code examples gave the expected results without erroring
-    - Check for length of the code examples and iteratively adjust to make it easy
+      - Check all code examples gave the expected results without erroring
+      - Check for length of the code examples and iteratively adjust to make it easy
         to read