Feature: Add Source support

.github/workflows/powershell.yml

@@ -7,6 +7,7 @@ on:
       - 'docs/**'
       - 'Changelog.md'
       - 'README.md'
+      - src/internal/Export-HelpToMd.ps1
   pull_request:
     branches: [ "main" ]
 
@@ -70,7 +71,7 @@ jobs:
       image: mcr.microsoft.com/powershell:${{ matrix.pwshv }}-ubuntu-22.04
     strategy:
       matrix:
-        pwshv: ['7.3','7.4']
+        pwshv: ['7.4','preview-7.5']
 
     steps:
       - uses: actions/checkout@v4

build.ps1

@@ -35,11 +35,12 @@ if ( (Get-Command 'nbgv' -CommandType Application -ErrorAction SilentlyContinue)
     if (!$PSBoundParameters.ContainsKey('Revision')) { $Revision = $(nbgv get-version -v VersionRevision) }
 }
 
+$module = 'potel'
 $parent = $PSScriptRoot
 $parent = [string]::IsNullOrEmpty($parent) ? $pwd.Path : $parent
 $src = Join-Path $parent -ChildPath "src"
 $docs = Join-Path $parent -ChildPath "docs"
-$publish = Join-Path $parent -ChildPath "publish" -AdditionalChildPath 'potel'
+$publish = [System.IO.Path]::Combine($parent, "publish", $module)
 $csproj = Join-Path -Path $src -ChildPath "dotnet" -AdditionalChildPath "potel.csproj"
 $bin = Join-Path -Path $src -ChildPath "dotnet" -AdditionalChildPath "bin"
 $obj = Join-Path -Path $src -ChildPath "dotnet" -AdditionalChildPath "obj"
@@ -55,19 +56,20 @@ Write-Host "dotnet: $([Environment]::Version)"
 Write-Host "ps: $($PSVersionTable.PSVersion)"
 
 $manifest = @{
-    Path                  = Join-Path -Path $publish -ChildPath 'potel.psd1'
+    Path                  = Join-Path -Path $publish -ChildPath  "$module.psd1"
     Author                = 'Chris Hunt'
     CompanyName           = 'Chris Hunt'
-    Copyright             = 'Chris Hunt'
+    Copyright             = '(c) Chris Hunt. All rights reserved.'
     CompatiblePSEditions  = "Core"
     Description           = 'PowerShell module for collecting and sending Open Telemetry'
-    LicenseUri            = 'https://github.com/cdhunt/potel/blob/main/LICENSE'
+    GUID                  = '0be70178-3d95-45cd-b3c5-d024ba8c18c7'
+    LicenseUri            = "https://github.com/cdhunt/$module/blob/main/LICENSE"
     FunctionsToExport     = @()
     ModuleVersion         = [version]::new($Major, $Minor, $Build, $Revision)
     ProcessorArchitecture = 'Amd64'
-    PowerShellVersion     = '7.3'
-    ProjectUri            = 'https://github.com/cdhunt/potel'
-    RootModule            = 'potel.psm1'
+    PowerShellVersion     = '7.4'
+    ProjectUri            = "https://github.com/cdhunt/$module"
+    RootModule            = "$module.psm1"
     Tags                  = @('otel', 'distributed-tracing', 'metrics', 'telemetry', 'diagnostics')
 }
 
@@ -94,7 +96,7 @@ function Build {
         Get-ChildItem -Path $_ -filter "potel.dll" | Remove-Item -Force -ErrorAction SilentlyContinue
     }
 
-    Copy-Item -Path "$src/potel.psm1" -Destination $publish
+    Copy-Item -Path "$src/$module.psm1" -Destination $publish
     Copy-Item -Path @("$parent/LICENSE", "$parent/README.md") -Destination $publish
 
     $internalFunctions = Get-ChildItem -Path "$src/internal/*.ps1"
@@ -129,11 +131,20 @@ function Build {
 function Test {
     param ()
 
-    if ($null -eq (Get-Module Pester -ListAvailable)) {
-        Install-Module -Name Pester -Confirm:$false -Force
+    if ($null -eq (Get-Module Pester -ListAvailable | Where-Object { [version]$_.Version -ge [version]"5.5.0" })) {
+        Install-Module -Name Pester -MinimumVersion 5.5.0 -Confirm:$false -Force
     }
 
-    Invoke-Pester -Path test
+    $config = New-PesterConfiguration -Hashtable @{
+        Run        = @{ Path = "test" }
+        TestResult = @{
+            Enabled      = $true
+            OutputFormat = "NUnitXml"
+        }
+        Output     = @{ Verbosity = "Detailed" }
+    }
+
+    Invoke-Pester -Configuration $config
 }
 
 function ChangeLog {
@@ -181,24 +192,28 @@ function Publish {
 function Docs {
     param ()
 
+    if ($null -eq (Get-Module Build-Docs -ListAvailable | Where-Object { [version]$_.Version -ge [version]"0.2.0.2" })) {
+        Install-Module -Name Build-Docs -MinimumVersion 0.2.0.2 -Confirm:$false -Force
+    }
+
     Import-Module $publish -Force
 
-    $commands = Get-Command -Module potel
-    $HelpToMd = Join-Path -Path $src -ChildPath 'internal' -AdditionalChildPath 'Export-HelpToMd.ps1'
-    . $HelpToMd
+    $help = Get-HelpModuleData $module
 
-    @('# Potel', [System.Environment]::NewLine) | Set-Content -Path "$docs/README.md"
-    $($manifest.Description) | Add-Content -Path "$docs/README.md"
-    @('## Cmdlets', [System.Environment]::NewLine) | Add-Content -Path "$docs/README.md"
+    # docs/README.md
+    $help | New-HelpDoc |
+    Add-ModuleProperty Name -H1 |
+    Add-ModuleProperty Description |
+    Add-HelpDocText "Commands" -H2 |
+    Add-ModuleCommand -AsLinks |
+    Out-HelpDoc -Path 'docs/README.md'
 
-    foreach ($command in $Commands | Sort-Object -Property Verb) {
+    # Individual Commands
+    foreach ($command in $help.Commands) {
         $name = $command.Name
-        $docPath = Join-Path -Path $docs -ChildPath "$name.md"
-        $help = Get-Help -Name $name
-
-        Export-HelpToMd $help | Set-Content -Path $docPath
-
-        "- [$name]($name.md) $($help.Synopsis)" | Add-Content -Path "$docs/README.md"
+        $doc = New-HelpDoc -HelpModuleData $help
+        $doc.Text = $command.ToMD()
+        $doc | Out-HelpDoc -Path "docs/$name.md"
     }
 
     ChangeLog | Set-Content -Path "$parent/Changelog.md"

docs/Add-ActivityEvent.md

@@ -0,0 +1,18 @@
+# Add-ActivityEvent
+
+Add a timestamped message to an Activity.
+
+## Parameters
+
+### Parameter Set 1
+
+- `[String]` **Message** _The message string for the ActivityEvent._ Mandatory
+- `[Activity]` **Activity** _An instance of an Activity._ Mandatory, ValueFromPipeline
+
+## Links
+
+- [Start-Activity](Start-Activity.md)
+
+## Notes
+
+Events are timestamped messages that can attach an arbitrary stream of additional diagnostic data to Activities.

docs/Add-ActivityTag.md

@@ -0,0 +1,18 @@
+# Add-ActivityTag
+
+Add key-value data called Tags to an Activity.
+
+## Parameters
+
+### Parameter Set 1
+
+- `[Hashtable]` **Tags** _A collection of key/value pairs._ Mandatory
+- `[Activity]` **Activity** _An instance of an Activity._ Mandatory, ValueFromPipeline
+
+## Links
+
+- [Start-Activity](Start-Activity.md)
+
+## Notes
+
+Commonly used to store any parameters of the work that may be useful for diagnostics

docs/Add-ExporterConsole.md

@@ -1,38 +1,32 @@
 # Add-ExporterConsole
 
-
 Adds OpenTelemetry.Exporter.Console
-## Parameters
 
+## Parameters
 
 ### Parameter Set 1
 
-
-- `[TracerProviderBuilderBase]` **TracerProvider** _Instance of TracerProviderBuilderBase._.  Mandatory, ValueFromPipeline
-
+- `[TracerProviderBuilderBase]` **TracerProvider** _Instance of TracerProviderBuilderBase._ Mandatory, ValueFromPipeline
 
 ### Parameter Set 2
 
-
-- `[MeterProviderBuilderBase]` **MeterBuilder** _Instance of MeterProviderBuilderBase._.  Mandatory, ValueFromPipeline
-
+- `[MeterProviderBuilderBase]` **MeterBuilder** _Instance of MeterProviderBuilderBase._ Mandatory, ValueFromPipeline
 
 ## Examples
 
-
 ### Example 1
 
 
 
-
 ```powershell
 New-TracerProviderBuilder | Add-HttpClientInstrumentation | Add-ExporterConsole | Start-Trace
 ```
 
-
 ## Links
 
-
-- [New-TracerBuilder](New-TracerBuilder.md)
 - [Add-HttpClientInstrumentation](Add-HttpClientInstrumentation.md)
 - [Start-Tracer](Start-Tracer.md)
+
+## Outputs
+
+- `TracerProviderBuilderBase`

docs/Add-ExporterOtlpTrace.md

@@ -1,70 +1,57 @@
 # Add-ExporterOtlpTrace
 
-
 Adds OpenTelemetry.Exporter.Console
-## Parameters
 
+## Parameters
 
 ### Parameter Set 1
 
-
-- `[TracerProviderBuilderBase]` **TracerProvider** _Instance of TracerProviderBuilderBase._.  Mandatory, ValueFromPipeline
-- `[String]` **Endpoint** _OTLP endpoint address_.  Mandatory
-- `[Hashtable]` **Headers** _Headers to send_.  
-- `[UInt32]` **Timeout** _Send timeout in ms_.  
-- `[String]` **Protocol** _'grpc' or 'http/protobuf'_.  
-
+- `[TracerProviderBuilderBase]` **TracerProvider** _Instance of TracerProviderBuilderBase._ Mandatory, ValueFromPipeline
+- `[String]` **Endpoint** _OTLP endpoint address_ Mandatory
+- `[Hashtable]` **Headers** _Headers to send_ 
+- `[UInt32]` **Timeout** _Send timeout in ms_ 
+- `[String]` **Protocol** _'grpc' or 'http/protobuf'_ 
 
 ### Parameter Set 2
 
-
-- `[MeterProviderBuilderBase]` **MeterBuilder** _Instance of MeterProviderBuilderBase._.  Mandatory, ValueFromPipeline
-- `[String]` **Endpoint** _OTLP endpoint address_.  Mandatory
-- `[Hashtable]` **Headers** _Headers to send_.  
-- `[UInt32]` **Timeout** _Send timeout in ms_.  
-- `[String]` **Protocol** _'grpc' or 'http/protobuf'_.  
-
+- `[MeterProviderBuilderBase]` **MeterBuilder** _Instance of MeterProviderBuilderBase._ Mandatory, ValueFromPipeline
+- `[String]` **Endpoint** _OTLP endpoint address_ Mandatory
+- `[Hashtable]` **Headers** _Headers to send_ 
+- `[UInt32]` **Timeout** _Send timeout in ms_ 
+- `[String]` **Protocol** _'grpc' or 'http/protobuf'_ 
 
 ## Examples
 
-
 ### Example 1
 
 
 
-
 ```powershell
 New-TracerProviderBuilder | Add-HttpClientInstrumentation | Add-ExporterOtlpTrace -Endpoint http://localhost:9999 | Start-Trace
 ```
-
-
 ### Example 2
 
-
 Configure the Otlp Exporter for Honeycomb.
 
-
 ```powershell
 Add-ExporterOtlpTrace  https://api.honeycomb.io:443 -Headers @{'x-honeycomb-team'='token'}
 ```
-
-
 ### Example 3
 
-
 Configure the Otlp Exporter for Dynatrace.
 
-
 ```powershell
 Add-ExporterOtlpTrace -Endpoint https://{your-environment-id}.live.dynatrace.com/api/v2/otlp -Headers @{'Authorization'='Api-Token dt.....'} -Protocol 'http/protobuf'
 ```
 
-
 ## Links
 
-
 - [New-TracerProviderBuilder](New-TracerProviderBuilder.md)
 - [Add-HttpClientInstrumentation](Add-HttpClientInstrumentation.md)
 - [Start-Tracer](Start-Tracer.md)
 - [https://docs.honeycomb.io/getting-data-in/opentelemetry-overview/#using-the-honeycomb-opentelemetry-endpoint](https://docs.honeycomb.io/getting-data-in/opentelemetry-overview/#using-the-honeycomb-opentelemetry-endpoint)
 - [https://docs.dynatrace.com/docs/extend-dynatrace/opentelemetry/getting-started/otlp-export](https://docs.dynatrace.com/docs/extend-dynatrace/opentelemetry/getting-started/otlp-export)
+
+## Outputs
+
+- `TracerProviderBuilderBase`

docs/Add-HttpClientInstrumentation.md

@@ -1,30 +1,27 @@
 # Add-HttpClientInstrumentation
 
-
 Adds Http Client Instrumentation
-## Parameters
 
+## Parameters
 
 ### Parameter Set 1
 
-
-- `[TracerProviderBuilderBase]` **TracerProvider** _Instance of TracerProviderBuilderBase._.  Mandatory, ValueFromPipeline
-
+- `[TracerProviderBuilderBase]` **TracerProvider** _Instance of TracerProviderBuilderBase._ Mandatory, ValueFromPipeline
 
 ## Examples
 
-
 ### Example 1
 
 
 
-
 ```powershell
 New-TracerProviderBuilder | Add-HttpClientInstrumentation
 ```
 
-
 ## Links
 
-
 - [New-TracerProviderBuilder](New-TracerProviderBuilder.md)
+
+## Outputs
+
+- `TracerProviderBuilderBase`

docs/Add-ResourceConfiguration.md

@@ -1,40 +1,35 @@
 # Add-ResourceConfiguration
 
-
 Adds a Resource Configuration to a Tracer. A resource represents the entity producing telemetry as resource attributes.
-## Parameters
 
+## Parameters
 
 ### Parameter Set 1
 
-
-- `[String]` **ServiceName** _An identifier usually base off of the name of the Service or Application generating the traces._.  Mandatory
-- `[Hashtable]` **Attribute** _A key-value pair. Used across telemetry signals - e.g. in Traces to attach data to an Activity (Span)_.  Mandatory
-- `[TracerProviderBuilderBase]` **TracerProvider** _A TracerProviderBuilderBase object_.  Mandatory, ValueFromPipeline
-
+- `[String]` **ServiceName** _An identifier usually base off of the name of the Service or Application generating the traces._ Mandatory
+- `[Hashtable]` **Attribute** _A key-value pair. Used across telemetry signals - e.g. in Traces to attach data to an Activity (Span)_ Mandatory
+- `[TracerProviderBuilderBase]` **TracerProvider** _A TracerProviderBuilderBase object_ Mandatory, ValueFromPipeline
 
 ### Parameter Set 2
 
-
-- `[String]` **ServiceName** _An identifier usually base off of the name of the Service or Application generating the traces._.  Mandatory
-- `[Hashtable]` **Attribute** _A key-value pair. Used across telemetry signals - e.g. in Traces to attach data to an Activity (Span)_.  Mandatory
-- `[MeterProviderBuilderBase]` **MeterBuilder** _Instance of MeterProviderBuilderBase_.  Mandatory, ValueFromPipeline
-
+- `[String]` **ServiceName** _An identifier usually base off of the name of the Service or Application generating the traces._ Mandatory
+- `[Hashtable]` **Attribute** _A key-value pair. Used across telemetry signals - e.g. in Traces to attach data to an Activity (Span)_ Mandatory
+- `[MeterProviderBuilderBase]` **MeterBuilder** _Instance of MeterProviderBuilderBase_ Mandatory, ValueFromPipeline
 
 ## Examples
 
-
 ### Example 1
 
 
 
-
 ```powershell
 New-TracerProviderBuilder | Add-HttpClientInstrumentation | Add-ResourceConfiguration -ServiceName $ExecutionContext.Host.Name -Attribute @{"host.name" = $(hostname)} | Add-ExporterConsole | Start-Tracer
 ```
 
-
 ## Links
 
-
 - [https://opentelemetry.io/docs/instrumentation/net/resources/](https://opentelemetry.io/docs/instrumentation/net/resources/)
+
+## Outputs
+
+- `TracerProviderBuilderBase`