From 046c2d27a803bf1998f48d507797979ccefbfded Mon Sep 17 00:00:00 2001 From: Roderick Bant <13252390+webtonize@users.noreply.github.com> Date: Sun, 12 Mar 2023 15:05:37 +0000 Subject: [PATCH] Updates to internal help --- docs/ConvertFrom-AzureRegion.md | 14 ++-- docs/Get-AzureRegionWithLowestWattTime.md | 18 +++-- docs/Get-WattTime.md | 9 ++- docs/Get-WattTimeAuthToken.md | 7 +- docs/Get-WattTimeForAzureRegion.md | 18 +++-- docs/New-WattTimeAccount.md | 21 +++--- src/PSWattTime/PSWattTime.psd1 | 6 +- src/PSWattTime/PSWattTime.psm1 | 86 ++++++++++++++++++----- 8 files changed, 134 insertions(+), 45 deletions(-) diff --git a/docs/ConvertFrom-AzureRegion.md b/docs/ConvertFrom-AzureRegion.md index 1fdac3f..c2c3998 100644 --- 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 index aeb3613..eb70cba 100644 --- 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] [-AuthToken] [< ``` ## 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 index debc7de..56882e7 100644 --- 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 index 1adf5ef..fcaaa1c 100644 --- 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 index efa3bb1..59dc273 100644 --- 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 index fbf43c2..94a60c7 100644 --- 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] [-Password] [-Email] ``` ## 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 index e95a7da..8105976 100644 --- 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 index 15b1630..ae6e975 100644 --- 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()]