with_units_base: fix docstrings, add to tutorial and explanation

docs/src/explanation/per_unit.md

@@ -19,8 +19,11 @@ These three unit bases allow easy conversion between unit systems.
 This allows `PowerSystems.jl` users to input data in the formats they have available,
 as well as view data in the unit system that is most intuitive to them.
 
-You can get and set the unit system setting of a `System` with [`get_units_base`](@ref)
-and [`set_units_base_system!`](@ref).
+You can get and set the unit system setting of a `System` with [`get_units_base`](@ref) and
+[`set_units_base_system!`](@ref). To support a less stateful style of programming,
+`PowerSystems.jl` provides the `Logging.with_logger`-inspired "context manager"-type
+function [`with_units_base`](@ref), which sets the unit system to a particular value,
+performs some action, then automatically sets the unit system back to its previous value.
 
 Conversion between unit systems does not change
 the stored parameter values. Instead, unit system conversions are made when accessing

docs/src/tutorials/creating_system.md

@@ -357,6 +357,18 @@ get_rating(retrieved_component)
 See that now the data is now 1.0 (5.0 MVA per-unitized by the generator (i.e., the device's)
 `base_power` of 5.0 MVA), which is the format we used to originally define the device.
 
+As a shortcut to temporarily set the `System`'s unit system to a particular value, perform
+some action, and then automatically set it back to what it was before, we can use
+`with_units_base` and a [`do` block](https://docs.julialang.org/en/v1/manual/functions/#Do-Block-Syntax-for-Function-Arguments):
+
+```@repl basics
+with_units_base(sys, "NATURAL_UNITS") do
+    # Everything inside this block will run as if the unit system were NATURAL_UNITS
+    get_rating(retrieved_component)
+end
+get_units_base(sys)  # Unit system goes back to previous value when the block ends
+```
+
 Recall that if you ever need to check a `System`'s settings, including the unit system being
 used by all the getter functions, you can always just print the `System`:
 

src/base.jl

@@ -523,8 +523,6 @@ _set_units_base!(system::System, settings::String) =
     _set_units_base!(system::System, UNIT_SYSTEM_MAPPING[uppercase(settings)])
 
 """
-`set_units_base_system!(system::System, units::Union{UnitSystem, String})`
-
 Sets the units base for the getter functions on the devices. It modifies the behavior of all getter functions
 
 # Examples
@@ -551,10 +549,8 @@ function get_units_base(system::System)
 end
 
 """
-`with_units_base(function, system, units::Union{UnitSystem, String})`
-
-A "context manager" similar to `Logging.with_logger` that sets the system's units base to
-the given value, executes the function, then sets the units base back.
+A "context manager" that sets the [`System`](@ref)'s [units base](@ref per_unit) to the
+given value, executes the function, then sets the units base back.
 
 # Examples
 ```julia