Skip to content

Commit 36b7e92

Browse files
HeyItsGilbertclaude
HeyItsGilbert
and
claude
authored
Add comprehensive PowerShellBuild documentation section (#42)
## Summary This PR adds a complete documentation section for PowerShellBuild, the official companion module to psake that provides pre-built tasks for PowerShell module projects. The new section includes five focused guides covering introduction, getting started, task reference, configuration, and a real-world example. ## Key Changes - **New documentation category**: Created `docs/powershellbuild/` with five comprehensive markdown files: - `introduction.md` — Overview of PowerShellBuild, its relationship to psake, and when to use it - `getting-started.md` — Step-by-step guide to set up PowerShellBuild in a new project with minimal configuration - `task-reference.md` — Complete reference of all pre-built tasks with dependency graph (Mermaid diagram) and descriptions - `configuration.md` — Full `$PSBPreference` hashtable reference with all configuration options organized by category - `real-world-example.md` — Production-ready example project showing custom tasks, CI/CD integration, and PSGallery publishing - **Sidebar integration**: Updated `sidebars.ts` to add the new PowerShellBuild category to the guides sidebar (positioned between "Advanced Techniques" and "Build Type Examples") - **Category metadata**: Added `_category_.json` for Docusaurus sidebar auto-generation ## Notable Implementation Details - The task reference includes a Mermaid diagram visualizing the complete task dependency graph - Configuration reference is organized into logical sections (General, Build, Test, Help, Docs, Publish, Sign) with tables for easy lookup - Real-world example demonstrates combining PowerShellBuild's pre-built tasks with custom project-specific tasks - Getting started guide includes both psake and Invoke-Build approaches - All examples are production-ready and include GitHub Actions CI/CD workflow configuration https://claude.ai/code/session_01TU1s3wRx7eGZhMJJXvY5Kz --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 10c8143 commit 36b7e92

9 files changed

Lines changed: 1208 additions & 0 deletions

File tree

‎docs/powershellbuild/_category_.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "PowerShellBuild",
3+
"position": 3,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "Learn how to use PowerShellBuild, the official companion module that provides reusable psake tasks for building, testing, and publishing PowerShell modules."
7+
}
8+
}

‎docs/powershellbuild/configuration.md‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
---
2+
title: "Configuration Reference"
3+
description: "Complete reference for the $PSBPreference hashtable and task dependency variables in PowerShellBuild."
4+
---
5+
6+
# Configuration Reference
7+
8+
PowerShellBuild exposes all of its settings through a single hashtable called `$PSBPreference`. Override values in the `properties` block of your `psakeFile.ps1`. Task dependency chains can also be customized via separate variables set outside the `properties` block.
9+
10+
## Setting Preferences
11+
12+
```powershell title="psakeFile.ps1"
13+
properties {
14+
# Override any $PSBPreference keys here
15+
$PSBPreference.General.ModuleName = 'MyModule'
16+
$PSBPreference.Build.OutDir = "$PSScriptRoot/build"
17+
$PSBPreference.Test.ScriptAnalysis.Enabled = $true
18+
$PSBPreference.Test.CodeCoverage.Enabled = $true
19+
$PSBPreference.Test.CodeCoverage.Threshold = 0.80
20+
$PSBPreference.Publish.PSRepositoryApiKey = $env:PSGALLERY_API_KEY
21+
}
22+
23+
task default -depends Build
24+
task Build -FromModule PowerShellBuild -Version '0.7.1'
25+
```
26+
27+
Values not overridden retain their defaults as defined in PowerShellBuild's `build.properties.ps1`.
28+
29+
---
30+
31+
## General
32+
33+
| Setting | Default | Description |
34+
|---------|---------|-------------|
35+
| `General.ProjectRoot` | (auto-detected) | Root directory of the project |
36+
| `General.SrcRootDir` | `$ProjectRoot/src` | Directory containing module source files |
37+
| `General.ModuleName` | (basename of `.psd1`) | Name of the module |
38+
| `General.ModuleVersion` | (from manifest) | Module version number |
39+
| `General.ModuleManifestPath` | (auto-detected) | Path to the `.psd1` manifest |
40+
41+
---
42+
43+
## Build
44+
45+
| Setting | Default | Description |
46+
|---------|---------|-------------|
47+
| `Build.OutDir` | `$ProjectRoot/build` | Root output directory |
48+
| `Build.ModuleOutDir` | `$OutDir/$ModuleName` | Module-specific output subdirectory (computed) |
49+
| `Build.CompileModule` | `$false` | If `$true`, concatenate all `.ps1` source files into a single `.psm1` |
50+
| `Build.CompileDirectories` | `'Enum','Classes','Private','Public'` | Directories whose `.ps1` files are merged when compiling |
51+
| `Build.CopyDirectories` | `@()` | Directories copied as-is (not compiled) to the output |
52+
| `Build.Exclude` | `@()` | File patterns excluded from the output |
53+
54+
### Module Compilation
55+
56+
Setting `CompileModule = $true` merges all `.ps1` files from `CompileDirectories` into the root `.psm1`. This can improve module load time and is common for published modules.
57+
58+
```powershell
59+
properties {
60+
$PSBPreference.Build.CompileModule = $true
61+
$PSBPreference.Build.CompileDirectories = @('Enum', 'Classes', 'Private', 'Public')
62+
$PSBPreference.Build.CopyDirectories = @('data', 'lib')
63+
}
64+
```
65+
66+
---
67+
68+
## Test
69+
70+
| Setting | Default | Description |
71+
|---------|---------|-------------|
72+
| `Test.Enabled` | `$true` | Enable or disable Pester tests |
73+
| `Test.RootDir` | `$ProjectRoot/tests` | Directory containing Pester test files |
74+
| `Test.OutputFile` | `$null` | Path to write NUnitXml test results (useful for CI) |
75+
| `Test.OutputFormat` | `'NUnitXml'` | Test result format |
76+
| `Test.ImportModule` | `$false` | Import the built module before running tests |
77+
| `Test.OutputVerbosity` | `'Detailed'` | Pester output verbosity level |
78+
| `Test.SkipRemainingOnFailure` | `'None'` | Skip strategy after a test failure |
79+
80+
### Script Analysis
81+
82+
| Setting | Default | Description |
83+
|---------|---------|-------------|
84+
| `Test.ScriptAnalysis.Enabled` | `$true` | Run PSScriptAnalyzer |
85+
| `Test.ScriptAnalysis.FailBuildOnSeverityLevel` | `'Error'` | Build fails on violations at or above this severity (`'Error'`, `'Warning'`, `'Information'`) |
86+
| `Test.ScriptAnalysis.SettingsPath` | `./PSScriptAnalyzerSettings.psd1` | Path to a PSScriptAnalyzer settings file. Defaults to `PSScriptAnalyzerSettings.psd1` in the project root — if the file exists it is used automatically |
87+
88+
```powershell
89+
properties {
90+
# Fail on warnings too
91+
$PSBPreference.Test.ScriptAnalysis.FailBuildOnSeverityLevel = 'Warning'
92+
93+
# Override the default settings file location
94+
$PSBPreference.Test.ScriptAnalysis.SettingsPath = "$PSScriptRoot/build/analyzersettings.psd1"
95+
}
96+
```
97+
98+
### Code Coverage
99+
100+
| Setting | Default | Description |
101+
|---------|---------|-------------|
102+
| `Test.CodeCoverage.Enabled` | `$false` | Enable code coverage reporting |
103+
| `Test.CodeCoverage.Threshold` | `0.75` | Minimum coverage ratio (0.0–1.0); build fails below this |
104+
| `Test.CodeCoverage.Files` | (staged module files) | Files included in coverage analysis |
105+
| `Test.CodeCoverage.OutputFile` | `$null` | Path to write the coverage report |
106+
| `Test.CodeCoverage.OutputFileFormat` | `'JaCoCo'` | Coverage report format |
107+
108+
```powershell
109+
properties {
110+
$PSBPreference.Test.CodeCoverage.Enabled = $true
111+
$PSBPreference.Test.CodeCoverage.Threshold = 0.80
112+
$PSBPreference.Test.CodeCoverage.OutputFile = "$PSScriptRoot/coverage.xml"
113+
$PSBPreference.Test.CodeCoverage.OutputFileFormat = 'JaCoCo'
114+
}
115+
```
116+
117+
---
118+
119+
## Help
120+
121+
| Setting | Default | Description |
122+
|---------|---------|-------------|
123+
| `Help.DefaultLocale` | `'en-US'` | Locale used when generating MAML and updatable help |
124+
| `Help.UpdatableHelpOutDir` | `$null` | Directory where updatable help `.cab` files are written |
125+
| `Help.ConvertReadMeToAboutHelp` | `$false` | Convert `README.md` to an `about_<ModuleName>.help.txt` file |
126+
127+
---
128+
129+
## Docs
130+
131+
| Setting | Default | Description |
132+
|---------|---------|-------------|
133+
| `Docs.RootDir` | `$ProjectRoot/docs` | Directory for PlatyPS markdown source files |
134+
| `Docs.Overwrite` | `$false` | Overwrite existing markdown files when regenerating |
135+
| `Docs.AlphabeticParamsOrder` | `$false` | Sort parameters alphabetically in generated markdown |
136+
| `Docs.ExcludeDontShow` | `$false` | Exclude parameters marked `[DontShow]` |
137+
| `Docs.UseFullTypeName` | `$false` | Use fully-qualified type names instead of short names |
138+
139+
---
140+
141+
## Publish
142+
143+
| Setting | Default | Description |
144+
|---------|---------|-------------|
145+
| `Publish.PSRepository` | `'PSGallery'` | Name of the PowerShell repository to publish to |
146+
| `Publish.PSRepositoryApiKey` | `$null` | API key for authenticating with the repository |
147+
| `Publish.PSRepositoryCredential` | `$null` | `PSCredential` for authenticating with the repository |
148+
149+
```powershell
150+
properties {
151+
$PSBPreference.Publish.PSRepository = 'PSGallery'
152+
$PSBPreference.Publish.PSRepositoryApiKey = $env:PSGALLERY_API_KEY
153+
}
154+
```
155+
156+
---
157+
158+
## Sign
159+
160+
| Setting | Default | Description |
161+
|---------|---------|-------------|
162+
| `Sign.Enabled` | `$false` | Enable Authenticode signing |
163+
| `Sign.CertificateSource` | `'Auto'` | How to resolve the signing certificate (`'Auto'`, `'CertStore'`, `'Thumbprint'`, `'EnvVar'`, `'PfxFile'`) |
164+
| `Sign.CertStoreLocation` | `$null` | Certificate store path (e.g., `'Cert:\CurrentUser\My'`) |
165+
| `Sign.Thumbprint` | `$null` | Specific certificate thumbprint |
166+
| `Sign.CertificateEnvVar` | `'SIGNCERTIFICATE'` | Environment variable containing a Base64-encoded PFX |
167+
| `Sign.CertificatePasswordEnvVar` | `$null` | Environment variable containing the PFX password |
168+
| `Sign.PfxFilePath` | `$null` | Path to a PFX/P12 file |
169+
| `Sign.PfxFilePassword` | `$null` | Password for the PFX file |
170+
| `Sign.SkipCertificateValidation` | `$false` | Skip certificate validity checks (not recommended for production) |
171+
| `Sign.TimestampServer` | `$null` | RFC 3161 timestamp server URI |
172+
| `Sign.HashAlgorithm` | `'SHA256'` | Authenticode hash algorithm |
173+
| `Sign.FilesToSign` | `@('*.psd1','*.psm1','*.ps1')` | File patterns to sign in the output directory |
174+
175+
### Catalog
176+
177+
| Setting | Default | Description |
178+
|---------|---------|-------------|
179+
| `Sign.Catalog.Enabled` | `$false` | Create a Windows catalog (`.cat`) file |
180+
| `Sign.Catalog.Version` | `2` | Catalog hash version |
181+
| `Sign.Catalog.FileName` | (module name) | Catalog filename (without `.cat` extension) |
182+
183+
```powershell
184+
properties {
185+
$PSBPreference.Sign.Enabled = $true
186+
$PSBPreference.Sign.CertificateSource = 'EnvVar'
187+
$PSBPreference.Sign.TimestampServer = 'http://timestamp.digicert.com'
188+
$PSBPreference.Sign.Catalog.Enabled = $true
189+
}
190+
```
191+
192+
---
193+
194+
## Task Dependency Variables
195+
196+
To change which tasks a given task depends on, set these variables **outside** the `properties` block, before any PowerShellBuild task references:
197+
198+
| Variable | Controls dependencies of | Default |
199+
|----------|--------------------------|---------|
200+
| `$PSBCleanDependency` | `Clean` | `'Init'` |
201+
| `$PSBStageFilesDependency` | `StageFiles` | `'Clean'` |
202+
| `$PSBBuildHelpDependency` | `BuildHelp` | `'GenerateMarkdown', 'GenerateMAML'` |
203+
| `$PSBGenerateMarkdownDependency` | `GenerateMarkdown` | `'StageFiles'` |
204+
| `$PSBGenerateMAMLDependency` | `GenerateMAML` | `'GenerateMarkdown'` |
205+
| `$PSBGenerateUpdatableHelpDependency` | `GenerateUpdatableHelp` | `'BuildHelp'` |
206+
| `$PSBBuildDependency` | `Build` | `'StageFiles', 'BuildHelp'` |
207+
| `$PSBAnalyzeDependency` | `Analyze` | `'Build'` |
208+
| `$PSBPesterDependency` | `Pester` | `'Build'` |
209+
| `$PSBTestDependency` | `Test` | `'Pester', 'Analyze'` |
210+
| `$PSBPublishDependency` | `Publish` | `'Test'` |
211+
| `$PSBSignModuleDependency` | `SignModule` | `'Build'` |
212+
| `$PSBBuildCatalogDependency` | `BuildCatalog` | `'SignModule'` |
213+
| `$PSBSignCatalogDependency` | `SignCatalog` | `'BuildCatalog'` |
214+
| `$PSBSignDependency` | `Sign` | `'SignCatalog'` |
215+
216+
### Example: Remove Analyze from the Test pipeline
217+
218+
```powershell title="psakeFile.ps1"
219+
# Set outside properties block
220+
$PSBTestDependency = 'Pester' # Test only depends on Pester, not Analyze
221+
222+
properties {
223+
$PSBPreference.Test.ScriptAnalysis.Enabled = $false
224+
}
225+
226+
task default -depends Test
227+
task Test -FromModule PowerShellBuild -Version '0.7.1'
228+
```
229+
230+
## See Also
231+
232+
- [Task Reference](./task-reference) — What each task does
233+
- [Getting Started](./getting-started) — Minimal project setup
234+
- [Real-World Example](./real-world-example) — Configuration in context

0 commit comments

Comments
 (0)