Enhance documentation and workflows for PowerShell Universal tasks

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Added reusable Sampler tasks for packaging and deploying PowerShell Universal modules.
 - Added task-file alias exports compatible with `ModuleBuildTasks` in Sampler repositories.
+- Added WikiSource documentation and DscResource.DocGenerator build and publish workflows.
 
 ### Changed
 

README.md

@@ -22,3 +22,8 @@ The module provides tasks to:
 Configure the server under `UniversalServer` in `build.yaml`. Supply
 `UniversalServerAppToken` through the build environment or a local secrets file;
 do not commit tokens.
+
+## Documentation
+
+See the [GitHub wiki](https://github.com/SynEdgy/Sampler.PowerShellUniversalTasks/wiki)
+for installation, configuration, and task reference documentation.

RequiredModules.psd1

@@ -25,5 +25,5 @@
     'DscResource.AnalyzerRules' = 'latest'
     xDscResourceDesigner        = 'latest'
     'DscResource.DocGenerator'  = 'latest'
+    PlatyPS                     = 'latest'
 }
-

build.yaml

@@ -56,10 +56,19 @@ BuildWorkflow:
     - Build_NestedModules_ModuleBuilder
     - Create_changelog_release_output
 
+  docs:
+    - Create_Wiki_Output_Folder
+    - Generate_Markdown_For_Public_Commands
+    - Generate_External_Help_File_For_Public_Commands
+    - Clean_Markdown_Of_Public_Commands
+    - Copy_Source_Wiki_Folder
+    - Generate_Wiki_Sidebar
+    - Clean_Markdown_Metadata
+    - Package_Wiki_Content
 
   pack:
     - build
-
+    - docs
     - package_module_nupkg
 
   hqrmtest:
@@ -83,6 +92,7 @@ BuildWorkflow:
   publish:
     - Publish_Release_To_GitHub # Runs first, if token is expired it will fail early
     - publish_module_to_gallery
+    - Publish_GitHub_Wiki_Content
 
 ####################################################
 #              PESTER Configuration                #
@@ -177,6 +187,8 @@ ModuleBuildTasks:
     - '*.ib.tasks'
   DscResource.Test:
     - 'Task.*'
+  DscResource.DocGenerator:
+    - 'Task.*'
 
 
 # Invoke-Build Header to be used to 'decorate' the terminal output of the tasks.
@@ -203,10 +215,23 @@ GitConfig:
 GitHubConfig:
   GitHubFilesToAdd:
     - CHANGELOG.md
+  ReleaseAssets:
+    - output/CHANGELOG.md
+    - output/WikiContent.zip
   GitHubConfigUserName: github-actions[bot]
   GitHubConfigUserEmail: 41898282+github-actions[bot]@users.noreply.github.com
   UpdateChangelogOnPrerelease: false
 
+####################################################
+#      DscResource.DocGenerator Configuration      #
+####################################################
+DscResource.DocGenerator:
+  Publish_GitHub_Wiki_Content:
+    Debug: false
+  Generate_Wiki_Sidebar:
+    Debug: false
+    AlwaysOverwrite: true
+
 ####################################################
 #          Changelog Configuration                 #
 ####################################################

source/WikiSource/Configuration.md

@@ -0,0 +1,83 @@
+# Configuration
+
+The tasks resolve explicit task parameters first, then values from the
+`UniversalServer` section of `build.yaml`. Server URL and token values can also
+come from build environment variables.
+
+## UniversalServer settings
+
+```yaml
+UniversalServer:
+  UniversalServerUrl: https://psu.example.test
+  UniversalPSResourceRepositoryName: output
+  UniversalPSResourceRepositoryUrl: ./output/
+  UniversalPSResourceRepositoryAutoRemove: true
+  UniversalRepositoryStagingDirectoryName: PsuRepository
+  UniversalRepositoryZipName:
+  UniversalRepositoryAsModule: false
+  UniversalUnpinned: true
+```
+
+| Setting | Default | Description |
+|---|---|---|
+| `UniversalServerUrl` | None | Base URL of the PowerShell Universal server. |
+| `UniversalServerAppToken` | None | Application token. Prefer an environment variable or `secrets.local.ps1` instead of committing it. |
+| `UniversalPSResourceRepositoryName` | `output` | Resource repository name used for module installation. |
+| `UniversalPSResourceRepositoryUrl` | `./output/` | Repository URL or local path. Relative paths resolve from the consumer repository root. |
+| `UniversalPSResourceRepositoryAutoRemove` | `true` | Remove the resource repository after the installation attempt. |
+| `UniversalRepositoryStagingDirectoryName` | `PsuRepository` | Staging directory created below the build output directory. |
+| `UniversalRepositoryZipName` | `<ProjectName>.<ModuleVersion>.zip` | Optional explicit offline repository package name. |
+| `UniversalRepositoryAsModule` | `false` | Value sent to the deployment endpoint's `asModule` query parameter. |
+| `UniversalUnpinned` | `true` | Value sent to the deployment endpoint's `unpinned` query parameter. |
+
+## Authentication
+
+The deployment tasks require `UniversalServerAppToken`. In CI, map a secret to
+the environment variable:
+
+```yaml
+env:
+  UniversalServerAppToken: ${{ secrets.UniversalServerAppToken }}
+```
+
+For local development, use the ignored `secrets.local.ps1` file:
+
+```powershell
+$UniversalServerAppToken = '<token>'
+```
+
+The token is used only by build and deployment tasks. It is not intended for
+PowerShell Universal runtime scripts, apps, or dashboard endpoints.
+
+## PowerShell resource repository deployment
+
+`publish_module_from_psresource_repos_to_universal_server` queries the server
+for `UniversalPSResourceRepositoryName`.
+
+- A matching trusted repository is reused.
+- A differing repository is removed and recreated when
+  `UniversalPSResourceRepositoryAutoRemove` is `true`.
+- A missing repository is created.
+- The module is installed synchronously from that repository.
+- The repository is removed after deployment when auto-remove is enabled.
+
+## Offline automation repository layout
+
+`package_universal_automation_repository` creates:
+
+```text
+PsuRepository/
+|-- repository.psd1
+`-- Modules/
+    |-- MyModule/
+    |   `-- 1.0.0/
+    `-- MyDependency/
+        `-- 2.0.0/
+```
+
+The zip contains the project module and recursively resolved `RequiredModules`
+dependencies. `repository.psd1` identifies the project module that PowerShell
+Universal should load from the `Modules` directory.
+
+Keep `UniversalRepositoryAsModule` set to `false` for this full repository
+layout.

source/WikiSource/Getting-Started.md

@@ -0,0 +1,105 @@
+# Getting Started
+
+## Prerequisites
+
+- A PowerShell module repository based on Sampler.
+- PowerShell 7 or Windows PowerShell 5.1.
+- Access to a PowerShell Universal server for deployment tasks.
+- A PowerShell Universal application token for authenticated deployments.
+
+## Install the task module
+
+Add the module to the consumer repository's `RequiredModules.psd1`:
+
+```powershell
+@{
+    Sampler.PowerShellUniversalTasks = 'latest'
+}
+```
+
+For released versions, the module can also be installed directly:
+
+```powershell
+Install-PSResource -Name Sampler.PowerShellUniversalTasks
+```
+
+## Import the task file
+
+Add the module to `ModuleBuildTasks` in the consumer repository's `build.yaml`:
+
+```yaml
+ModuleBuildTasks:
+  Sampler.PowerShellUniversalTasks:
+    - 'Task.*'
+```
+
+Sampler imports the module and dot-sources the task file through the exported
+`Task.Publish_PowerShellUniversal` alias.
+
+## Configure the server
+
+Add a `UniversalServer` section:
+
+```yaml
+UniversalServer:
+  UniversalServerUrl: https://psu.example.test
+  UniversalPSResourceRepositoryName: output
+  UniversalPSResourceRepositoryUrl: ./output/
+  UniversalPSResourceRepositoryAutoRemove: true
+  UniversalRepositoryStagingDirectoryName: PsuRepository
+  UniversalRepositoryAsModule: false
+  UniversalUnpinned: true
+```
+
+Do not store `UniversalServerAppToken` in `build.yaml`. Supply it as an
+environment variable in CI:
+
+```powershell
+$env:UniversalServerAppToken = '<token>'
+```
+
+For local development, the tasks also dot-source `secrets.local.ps1` from the
+consumer repository root when that ignored file exists:
+
+```powershell
+$UniversalServerAppToken = '<token>'
+```
+
+## Add workflows
+
+Package and deploy the module directly:
+
+```yaml
+BuildWorkflow:
+  pack:
+    - build
+    - package_module_nupkg
+
+  deploy:
+    - pack
+    - publish_packed_module_to_universal_server
+```
+
+Package and deploy a complete offline automation repository:
+
+```yaml
+BuildWorkflow:
+  pack:
+    - build
+    - package_module_nupkg
+    - package_universal_automation_repository
+
+  deploy_repository:
+    - pack
+    - publish_universal_automation_repository_to_server
+```
+
+Run workflows through the Sampler entry point:
+
+```powershell
+./build.ps1 -Tasks pack
+./build.ps1 -Tasks deploy_repository
+```
+
+Review [Configuration](Configuration.md) before deployment and
+[Task Reference](Task-Reference.md) for task prerequisites and output details.

source/WikiSource/Home.md

@@ -0,0 +1,38 @@
+# Sampler.PowerShellUniversalTasks
+
+<sup>*Sampler.PowerShellUniversalTasks v#.#.#*</sup>
+
+`Sampler.PowerShellUniversalTasks` provides reusable Sampler and InvokeBuild tasks
+for packaging and deploying PowerShell modules to PowerShell Universal.
+
+## Start here
+
+- [Getting Started](Getting-Started.md) - install the module, import its task file, and add tasks
+  to a Sampler workflow.
+- [Configuration](Configuration.md) - configure the PowerShell Universal server, resource
+  repository, offline repository package, and deployment behavior.
+- [Task Reference](Task-Reference.md) - prerequisites, behavior, and outputs for every exported
+  InvokeBuild task.
+
+## Available tasks
+
+| Task | Purpose |
+|---|---|
+| `publish_packed_module_to_universal_server` | Upload a packed module directly to the PowerShell Universal module deployment endpoint. |
+| `publish_module_from_psresource_repos_to_universal_server` | Register or reconcile a PowerShell resource repository and install the module from it. |
+| `package_universal_automation_repository` | Package the built module and its dependencies as an offline automation repository. |
+| `publish_universal_automation_repository_to_server` | Upload and activate an offline automation repository package. |
+
+## Task discovery
+
+The module exports the `Task.Publish_PowerShellUniversal` alias. Sampler loads
+the task file through `ModuleBuildTasks`:
+
+```yaml
+ModuleBuildTasks:
+  Sampler.PowerShellUniversalTasks:
+    - 'Task.*'
+```
+
+Generated command pages and `_Sidebar.md` are rebuilt from `build.yaml`. Keep
+hand-authored wiki content in `source/WikiSource`.