Updates to internal help

cloudyspells · Mar 12, 2023 · 046c2d2 · 046c2d2
1 parent 99cb741
commit 046c2d2
Show file tree

Hide file tree

Showing 8 changed files with 134 additions and 45 deletions.
diff --git a/docs/ConvertFrom-AzureRegion.md b/docs/ConvertFrom-AzureRegion.md
@@ -1,7 +1,7 @@
 ---
 external help file: PSWattTime-help.xml
 Module Name: PSWattTime
-online version:
+online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/ConvertFrom-AzureRegion.md
 schema: 2.0.0
 ---
 
@@ -67,8 +67,14 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ### a string containing the WattTime ba for the given Azure Region
 ## NOTES
-A ba is WattTime's term for a balancing authority.
-A balancing authority is a regional entity that is responsible for maintaining the balance between supply and demand of electricity in a given region.
-For more information, see https://www.watttime.org/faq
+- A ba is WattTime's term for a balancing authority. A balancing authority is a regional entity that is responsible for maintaining the balance between supply and demand of electricity in a given region. For more information, see https://www.watttime.org/faq
+- This command, like the module, requires you to be connected to Azure via Connect-AzAccount
 
 ## RELATED LINKS
+
+[https://github.com/cloudyspells/PSWattTime/blob/main/docs/ConvertFrom-AzureRegion.md](https://github.com/cloudyspells/PSWattTime/blob/main/docs/ConvertFrom-AzureRegion.md)
+
+[https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeAuthToken.md](https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeAuthToken.md)
+
+[https://www.watttime.org/api-documentation/#determine-grid-region](https://www.watttime.org/api-documentation/#determine-grid-region)
+
diff --git a/docs/Get-AzureRegionWithLowestWattTime.md b/docs/Get-AzureRegionWithLowestWattTime.md
@@ -1,7 +1,7 @@
 ---
 external help file: PSWattTime-help.xml
 Module Name: PSWattTime
-online version:
+online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-AzureRegionWithLowestWattTime.md
 schema: 2.0.0
 ---
 
@@ -17,7 +17,7 @@ Get-AzureRegionWithLowestWattTime [-Regions] <String[]> [-AuthToken] <String> [<
 ```
 
 ## DESCRIPTION
-Get the current WattTime index for a given Azure Region
+Get the Azure region with the lowest wattTime index from a given set of regions
 
 ## EXAMPLES
 
@@ -44,7 +44,7 @@ Accept wildcard characters: False
 ```
 
 ### -AuthToken
-The authentication token to use for the request
+The WattTime API authentication token to use for the request
 
 ```yaml
 Type: String
@@ -66,9 +66,15 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 ## OUTPUTS
 
 ### System.Management.Automation.PSObject containing the following properties:
-###     ba: The WattTime ba for the given Azure Region
-###     percent: The current WattTime index for the given Azure Region
-###     region: The Azure Region for which the WattTime index was retrieved
+### - ba: The WattTime ba for the given Azure Region
+### - percent: The current WattTime index for the given Azure Region
+### - region: The Azure Region for which the WattTime index was retrieved
 ## NOTES
+This command, like the module, requires you to be connected to Azure via Connect-AzAccount
 
 ## RELATED LINKS
+
+[https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-AzureRegionWithLowestWattTime.md](https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-AzureRegionWithLowestWattTime.md)
+
+[https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeAuthToken.md](https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeAuthToken.md)
+
diff --git a/docs/Get-WattTime.md b/docs/Get-WattTime.md
@@ -1,7 +1,7 @@
 ---
 external help file: PSWattTime-help.xml
 Module Name: PSWattTime
-online version:
+online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTime.md
 schema: 2.0.0
 ---
 
@@ -71,3 +71,10 @@ A balancing authority is a regional entity that is responsible for maintaining t
 For more information, see https://www.watttime.org/faq
 
 ## RELATED LINKS
+
+[https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTime.md](https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTime.md)
+
+[https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeAuthToken.md](https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeAuthToken.md)
+
+[https://www.watttime.org/api-documentation/#real-time-emissions-index](https://www.watttime.org/api-documentation/#real-time-emissions-index)
+
diff --git a/docs/Get-WattTimeAuthToken.md b/docs/Get-WattTimeAuthToken.md
@@ -1,7 +1,7 @@
 ---
 external help file: PSWattTime-help.xml
 Module Name: PSWattTime
-online version:
+online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeAuthToken.md
 schema: 2.0.0
 ---
 
@@ -70,3 +70,8 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 This token should be used by the -AuthToken parameter of the other functions in this module
 
 ## RELATED LINKS
+
+[https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeAuthToken.md](https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeAuthToken.md)
+
+[https://www.watttime.org/api-documentation/#login-amp-obtain-token](https://www.watttime.org/api-documentation/#login-amp-obtain-token)
+
diff --git a/docs/Get-WattTimeForAzureRegion.md b/docs/Get-WattTimeForAzureRegion.md
@@ -1,7 +1,7 @@
 ---
 external help file: PSWattTime-help.xml
 Module Name: PSWattTime
-online version:
+online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeForAzureRegion.md
 schema: 2.0.0
 ---
 
@@ -44,7 +44,7 @@ Accept wildcard characters: False
 ```
 
 ### -AuthToken
-The authentication token to use for the request
+The WattTime API authentication token to use for the request
 
 ```yaml
 Type: String
@@ -66,9 +66,17 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 ## OUTPUTS
 
 ### System.Management.Automation.PSObject containing the following properties:
-###     ba: The WattTime ba for the given Azure Region
-###     percent: The current WattTime index for the given Azure Region
-###     region: The Azure Region for which the WattTime index was retrieved
+### - ba: The WattTime ba for the given Azure Region
+### - percent: The current WattTime index for the given Azure Region
+### - region: The Azure Region for which the WattTime index was retrieved
 ## NOTES
+This command, like the module, requires you to be connected to Azure via Connect-AzAccount
 
 ## RELATED LINKS
+
+[https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeForAzureRegion.md](https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeForAzureRegion.md)
+
+[https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTime.md](https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTime.md)
+
+[https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeAuthToken.md](https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeAuthToken.md)
+
diff --git a/docs/New-WattTimeAccount.md b/docs/New-WattTimeAccount.md
@@ -1,14 +1,14 @@
 ---
 external help file: PSWattTime-help.xml
 Module Name: PSWattTime
-online version:
+online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/New-WattTimeAccount.md
 schema: 2.0.0
 ---
 
 # New-WattTimeAccount
 
 ## SYNOPSIS
-Create a new WattTime account
+Create a new WattTime API account
 
 ## SYNTAX
 
@@ -18,8 +18,8 @@ New-WattTimeAccount [-Username] <String> [-Password] <String> [-Email] <String>
 ```
 
 ## DESCRIPTION
-Creates a new PSWattTime account with the specified username,
-password, email and organization
+Creates a new WattTime API account with the specified username,
+password, email and organization on watttime.org
 
 ## EXAMPLES
 
@@ -98,10 +98,15 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 ## OUTPUTS
 
 ### System.Management.Automation.PSObject containing the following properties:
-###     username: The username for the new account
-###     email: The email address for the new account
-###     org: The organization for the new account
-###     token: The authentication token for the new account
+### - user: The username for the new account
+### - ok: The response for user creation
 ## NOTES
+You can use an email address only once at WattTime.
+Registering multiple accounts will fail with an error.
 
 ## RELATED LINKS
+
+[https://github.com/cloudyspells/PSWattTime/blob/main/docs/New-WattTimeAccount.md](https://github.com/cloudyspells/PSWattTime/blob/main/docs/New-WattTimeAccount.md)
+
+[https://www.watttime.org/api-documentation/#register-new-user](https://www.watttime.org/api-documentation/#register-new-user)
+
diff --git a/src/PSWattTime/PSWattTime.psd1 b/src/PSWattTime/PSWattTime.psd1
@@ -12,7 +12,7 @@
 RootModule = 'PSWattTime.psm1'
 
 # Version number of this module.
-ModuleVersion = '1.0.2.0'
+ModuleVersion = '1.0.3.0'
 
 # Supported PSEditions
 # CompatiblePSEditions = @()
@@ -114,7 +114,7 @@ PrivateData = @{
         # IconUri = ''
 
         # ReleaseNotes of this module
-        ReleaseNotes = 'Added New-WattTimeAccount function for registering a new WattTime account'
+        ReleaseNotes = 'Updates to documentation and PowerShell internal help'
 
         # Prerelease string of this module
         # Prerelease = ''
@@ -130,7 +130,7 @@ PrivateData = @{
 } # End of PrivateData hashtable
 
 # HelpInfo URI of this module
-HelpInfoURI = ''
+HelpInfoURI = 'https://github.com/cloudyspells/PSWattTime#readme'
 
 # Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
 # DefaultCommandPrefix = ''

diff --git a/src/PSWattTime/PSWattTime.psm1 b/src/PSWattTime/PSWattTime.psm1
@@ -21,6 +21,12 @@ $script:azLocations = Get-AzLocation
 
     .OUTPUTS
     a string containing the authentication token for the WattTime API
+
+    .LINK
+    https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeAuthToken.md
+
+    .LINK
+    https://www.watttime.org/api-documentation/#login-amp-obtain-token
 #>
 function Get-WattTimeAuthToken {
     [CmdletBinding()]
@@ -59,6 +65,14 @@ function Get-WattTimeAuthToken {
     .NOTES
     A ba is WattTime's term for a balancing authority. A balancing authority is a regional entity that is responsible for maintaining the balance between supply and demand of electricity in a given region. For more information, see https://www.watttime.org/faq
 
+    .LINK
+    https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTime.md
+
+    .LINK
+    https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeAuthToken.md
+
+    .LINK
+    https://www.watttime.org/api-documentation/#real-time-emissions-index
 #>
 function Get-WattTime {
     [CmdletBinding()]
@@ -96,10 +110,20 @@ function Get-WattTime {
     ConvertFrom-AzureRegion -Region westeurope
 
     .NOTES
-    A ba is WattTime's term for a balancing authority. A balancing authority is a regional entity that is responsible for maintaining the balance between supply and demand of electricity in a given region. For more information, see https://www.watttime.org/faq
+    - A ba is WattTime's term for a balancing authority. A balancing authority is a regional entity that is responsible for maintaining the balance between supply and demand of electricity in a given region. For more information, see https://www.watttime.org/faq
+    - This command, like the module, requires you to be connected to Azure via Connect-AzAccount
 
     .OUTPUTS
     a string containing the WattTime ba for the given Azure Region
+
+    .LINK
+    https://github.com/cloudyspells/PSWattTime/blob/main/docs/ConvertFrom-AzureRegion.md
+
+    .LINK
+    https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeAuthToken.md
+
+    .LINK
+    https://www.watttime.org/api-documentation/#determine-grid-region
 #>
 function ConvertFrom-AzureRegion {
     [CmdletBinding()]
@@ -132,16 +156,28 @@ function ConvertFrom-AzureRegion {
     The Azure Region to get the WattTime index for
 
     .PARAMETER AuthToken
-    The authentication token to use for the request
+    The WattTime API authentication token to use for the request
 
     .EXAMPLE
     Get-WattTimeForAzureRegion -Region westeurope -AuthToken $authToken
 
     .OUTPUTS
     System.Management.Automation.PSObject containing the following properties:
-        ba: The WattTime ba for the given Azure Region
-        percent: The current WattTime index for the given Azure Region
-        region: The Azure Region for which the WattTime index was retrieved
+    - ba: The WattTime ba for the given Azure Region
+    - percent: The current WattTime index for the given Azure Region
+    - region: The Azure Region for which the WattTime index was retrieved
+
+    .NOTES
+    This command, like the module, requires you to be connected to Azure via Connect-AzAccount
+
+    .LINK
+    https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeForAzureRegion.md
+
+    .LINK
+    https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTime.md
+
+    .LINK
+    https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeAuthToken.md
 #>
 function Get-WattTimeForAzureRegion {
     [CmdletBinding()]
@@ -162,22 +198,31 @@ function Get-WattTimeForAzureRegion {
     Get the Azure region with the lowest wattTime index
 
     .DESCRIPTION
-    Get the current WattTime index for a given Azure Region
+    Get the Azure region with the lowest wattTime index from a given set of regions
 
     .PARAMETER Regions
     The list of Azure Regions to get the WattTime index for
 
     .PARAMETER AuthToken
-    The authentication token to use for the request
+    The WattTime API authentication token to use for the request
 
     .EXAMPLE
     Get-AzureRegionWithLowestWattTime -Regions westeurope,northeurope -AuthToken $authToken
 
     .OUTPUTS
     System.Management.Automation.PSObject containing the following properties:
-        ba: The WattTime ba for the given Azure Region
-        percent: The current WattTime index for the given Azure Region
-        region: The Azure Region for which the WattTime index was retrieved
+    - ba: The WattTime ba for the given Azure Region
+    - percent: The current WattTime index for the given Azure Region
+    - region: The Azure Region for which the WattTime index was retrieved
+
+    .NOTES
+    This command, like the module, requires you to be connected to Azure via Connect-AzAccount
+
+    .LINK
+    https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-AzureRegionWithLowestWattTime.md
+    
+    .LINK
+    https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeAuthToken.md
 #>
 function Get-AzureRegionWithLowestWattTime {
     [CmdletBinding()]
@@ -196,11 +241,11 @@ function Get-AzureRegionWithLowestWattTime {
 
 <#
     .SYNOPSIS
-    Create a new WattTime account
+    Create a new WattTime API account
 
     .DESCRIPTION
-    Creates a new PSWattTime account with the specified username,
-    password, email and organization
+    Creates a new WattTime API account with the specified username,
+    password, email and organization on watttime.org
 
     .PARAMETER Username
     The username for the new account
@@ -219,10 +264,17 @@ function Get-AzureRegionWithLowestWattTime {
 
     .OUTPUTS
     System.Management.Automation.PSObject containing the following properties:
-        username: The username for the new account
-        email: The email address for the new account
-        org: The organization for the new account
-        token: The authentication token for the new account
+    - user: The username for the new account
+    - ok: The response for user creation
+
+    .NOTES
+    You can use an email address only once at WattTime. Registering multiple accounts will fail with an error.
+
+    .LINK
+    https://github.com/cloudyspells/PSWattTime/blob/main/docs/New-WattTimeAccount.md
+
+    .LINK
+    https://www.watttime.org/api-documentation/#register-new-user
 #>
 function New-WattTimeAccount {
     [CmdletBinding()]