Merge pull request #18 from cloudyspells/feature/wiki

Feature/wiki
cloudyspells · Mar 15, 2023 · 6d75df3 · 6d75df3
2 parents 371664a + 4ae3117
commit 6d75df3
Show file tree

Hide file tree

Showing 10 changed files with 181 additions and 46 deletions.
diff --git a/.github/workflows/wiki.yml b/.github/workflows/wiki.yml
@@ -1,10 +1,17 @@
 # File: .github/workflows/wiki.yml
 
 on:
+  release:
+    types:
+      - "published"
   workflow_dispatch:
 
 name: Publish Wiki
 
+permissions:
+  contents: write
+  pull-requests: write
+
 jobs:
   build-publish-wiki:
     runs-on: ubuntu-22.04
@@ -17,24 +24,37 @@ jobs:
       - name: Checkout Wiki
         uses: actions/checkout@v3
         with:
-          repository: cloudyspells/PSWattTime.wiki
+          repository: ${{github.repository}}.wiki
           path: wiki
 
-      - name: Copy README.md as quickstart.md
+      - name: Copy wiki base sources
         shell: bash
         run: |
-          cp ./main/README.md ./wiki/quickstart.md
+          cp ./main/docs/wiki-src/*.md ./wiki/
+
+      - name: Login to Az PowerShell Module
+        uses: azure/login@v1
+        with:
+          creds: ${{ secrets.AZURE_CREDENTIALS }}
+          enable-AzPSSession: true
 
       - name: Generate Module docs
         shell: pwsh
         run: |
+          Set-PSRepository PSGallery -InstallationPolicy Trusted
+          Install-Module Az.Resources
           Install-Module PlatyPS
           Import-Module PlatyPS
           Import-Module ./main/src/PSWattTime
-          New-MarkdownHelp -Module PSWattTime -Force -OutputFolder ./wiki/
+          New-MarkdownHelp -Module PSWattTime `
+            -Verbose `
+            -Force `
+            -NoMetadata `
+            -OutputFolder ./wiki/
 
       - name: Commit and push changes to wiki
         shell: bash
+        working-directory: ./wiki
         run: |
           git config user.name github-actions
           git config user.email [email protected]

diff --git a/docs/ConvertFrom-AzureRegion.md b/docs/ConvertFrom-AzureRegion.md
@@ -1,10 +1,3 @@
----
-external help file: PSWattTime-help.xml
-Module Name: PSWattTime
-online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/ConvertFrom-AzureRegion.md
-schema: 2.0.0
----
-
 # ConvertFrom-AzureRegion
 
 ## SYNOPSIS

diff --git a/docs/Get-AzureRegionWithLowestWattTime.md b/docs/Get-AzureRegionWithLowestWattTime.md
@@ -1,10 +1,3 @@
----
-external help file: PSWattTime-help.xml
-Module Name: PSWattTime
-online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-AzureRegionWithLowestWattTime.md
-schema: 2.0.0
----
-
 # Get-AzureRegionWithLowestWattTime
 
 ## SYNOPSIS

diff --git a/docs/Get-WattTime.md b/docs/Get-WattTime.md
@@ -1,10 +1,3 @@
----
-external help file: PSWattTime-help.xml
-Module Name: PSWattTime
-online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTime.md
-schema: 2.0.0
----
-
 # Get-WattTime
 
 ## SYNOPSIS

diff --git a/docs/Get-WattTimeAuthToken.md b/docs/Get-WattTimeAuthToken.md
@@ -1,10 +1,3 @@
----
-external help file: PSWattTime-help.xml
-Module Name: PSWattTime
-online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeAuthToken.md
-schema: 2.0.0
----
-
 # Get-WattTimeAuthToken
 
 ## SYNOPSIS

diff --git a/docs/Get-WattTimeForAzureRegion.md b/docs/Get-WattTimeForAzureRegion.md
@@ -1,10 +1,3 @@
----
-external help file: PSWattTime-help.xml
-Module Name: PSWattTime
-online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeForAzureRegion.md
-schema: 2.0.0
----
-
 # Get-WattTimeForAzureRegion
 
 ## SYNOPSIS

diff --git a/docs/New-WattTimeAccount.md b/docs/New-WattTimeAccount.md
@@ -1,10 +1,3 @@
----
-external help file: PSWattTime-help.xml
-Module Name: PSWattTime
-online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/New-WattTimeAccount.md
-schema: 2.0.0
----
-
 # New-WattTimeAccount
 
 ## SYNOPSIS

diff --git a/docs/wiki-src/Home.md b/docs/wiki-src/Home.md
@@ -0,0 +1,30 @@
+PSWattTime Wiki
+===============
+
+PowerShell module for [WattTime.org](https://www.watttime.org/) API
+-------------------------------------------------------------------
+
+[![PowerShell Module Quality Assurance](https://github.com/cloudyspells/PSWattTime/actions/workflows/qa.yml/badge.svg)](https://github.com/cloudyspells/PSWattTime/actions/workflows/qa.yml)
+![GitHub release (latest by date)](https://img.shields.io/github/v/release/cloudyspells/PSWattTime)
+![PowerShell Gallery Version](https://img.shields.io/powershellgallery/v/PSWattTime)
+![PowerShell Gallery](https://img.shields.io/powershellgallery/dt/PSWattTime)
+
+
+This PowerShell module is intended for retrieving emissions data from
+[WattTime](https://www.watttime.org/) for a supplied Azure Region during
+resource deployments. This is a lightweight solution making use of only the
+limited functionality available with a free account at _WattTime_. This means
+the module is only able to get near-realtime emissions data and no prodictive
+values. This means this module is _not_ a real solution for reduced carbon
+deployments and -software. It _does_ however provide some nice realtime values
+so you can simulate the beheaviour of deployments and software based on 
+emissions data without the cost of a paid account for such data. For example in
+lab- or proof of concept environments.
+
+The intended use of this module is for setting the `Location` parameter
+on Azure IaC deployments in GitHub workflows using the included GitHub
+action.
+
+For a real-world solution with a commercial data provider, check out
+the [carbon-aware-sdk](https://github.com/Green-Software-Foundation/carbon-aware-sdk)
+by the [Green Software Foundation](https://greensoftware.foundation/)
diff --git a/docs/wiki-src/quickstart-github-action.md b/docs/wiki-src/quickstart-github-action.md
@@ -0,0 +1,52 @@
+Getting started with PSWattTime
+===============================
+
+Steps for using the GitHub Action
+---------------------------------
+
+This PowerShell module also comes with a _GitHub Action_ you can use
+in your GitHub workflows. Again you will need a pre-existing account
+for _WattTime_ and an Azure CLI/PowerShell secret configured in your repo
+
+### Example
+
+```yaml
+
+on:
+  pull_request:
+    branches:
+      - 'main'
+      - 'releases/**'
+
+name: Deploy to region with lowest emissions
+
+jobs:
+  deploy-to-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Get region with lowest emissions
+        uses: cloudyspells/[email protected]
+        id: watttime_action # Set step id for using output in deployment
+        with:
+          azure_credential: ${{ secrets.AZURE_CREDENTIALS }}
+          watttime_username: ${{ secrets.WATTTIMEUSERNAME }}
+          watttime_password: ${{ secrets.WATTTIMEPASSWORD }}
+          regions: '"westeurope","northeurope","uksouth","francecentral","germanynorth"'
+
+      - name: Login to Az PowerShell Module
+        uses: azure/login@v1
+        with:
+          creds: ${{ secrets.AZURE_CREDENTIALS }}
+          enable-AzPSSession: true
+
+      - uses: azure/arm-deploy@v1
+        name: Run Bicep deployment
+        with:
+          subscriptionId: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+          scope: subscription
+          region: ${{ steps.watttime_action.outputs.region }} # The region output from PSWattTime
+          template: src/bicep/main.bicep
+```
diff --git a/docs/wiki-src/quickstart-powershell.md b/docs/wiki-src/quickstart-powershell.md
@@ -0,0 +1,75 @@
+Getting started with PSWattTime
+===============================
+
+Steps for using the module in PowerShell
+----------------------------------------
+
+To get started with this module you will need an account on
+[WattTime](https://www.watttime.org/). See
+[the manual](https://www.watttime.org/api-documentation/#register-new-user)
+on registering an account. The module provides a function `New-WattTimeAccount`
+to create an account if you do not yet have one.
+
+You will also need the _Az.Resources_ PowerShell Module for Azure installed
+and connected to your Azure account. See
+[the installation manual](https://learn.microsoft.com/en-us/powershell/azure/install-az-ps)
+for the _Az_ module for instructions.
+
+To install the module from the [PowerShell Gallery](https://www.powershellgallery.com/packages/PSWattTime/).
+
+```powershell
+Install-Module -Name PSWattTime
+```
+
+To register an account with _WattTime_:
+
+```powershell
+New-WattTimeAccount -Username <YOUR_USERNAME> `
+  -Password '<YOUR_PASSWORD>' `
+  -Email '<[email protected]>' `
+  -Organization <YOUR_ORGANIZATION>
+```
+
+
+Authenticate to the _WattTime_ API:
+
+```powershell
+ $token = Get-WattTimeAuthToken -Username '<YOUR_WATTTIME_USERNAME>' `
+  -Password '<YOUR_WATTTIME_PASSWORD>'
+```
+
+Get current percentage of energy with emissions the 'westeurope' Azure region:
+
+```powershell
+PS C:\> Get-WattTimeForAzureRegion -Region westeurope -AuthToken $token
+
+ba         : NL
+freq       : 300
+percent    : 94
+point_time : 5-3-2023 13:15:00
+region     : westeurope
+
+```
+
+Determine the lowest emissions for the list of northeurope,
+westeurope, francecentral and uksouth Azure regions:
+
+```powershell
+PS C:\> Get-AzureRegionWithLowestWattTime -Regions westeurope,uksouth,northeurope,francecentral -AuthToken $token
+
+ba         : IE
+freq       : 300
+percent    : 69
+point_time : 5-3-2023 14:15:00
+region     : northeurope
+
+```
+
+### Module Functions
+
+- [ConvertFrom-AzureRegion](docs/ConvertFrom-AzureRegion.md)
+- [Get-AzureRegionWithLowestWattTime](docs/Get-AzureRegionWithLowestWattTime.md)
+- [Get-WattTime](docs/Get-WattTime.md)
+- [Get-WattTimeAuthToken](docs/Get-WattTimeAuthToken.md)
+- [Get-WattTimeForAzureRegion](docs/Get-WattTimeForAzureRegion.md)
+- [New-WattTimeAccount](docs/New-WattTimeAccount.md)