Skip to content

Commit 13bee8d

Browse files
tablackburnclaude
tablackburn
and
claude
committed
feat(init): split README and rename docs/en-US files during init
The repo's README.md was a placeholder-laden module README, which made it look like docs for a hypothetical {{ModuleName}} when viewed on GitHub. Split into two files so the GitHub template page sells the template itself. - README.md: rewritten as template documentation — what's included (build, CI, devcontainer, instructions, test infra), quick-start with Initialize- Template.ps1, placeholder reference table, and post-init project structure. - README.template.md: holds the original placeholder-based module README. The file-processing loop in Initialize-Template.ps1 still substitutes its placeholders, then the script moves it over README.md as the final step. - Initialize-Template.ps1: - Rename files in docs/en-US/ that contain {{ModuleName}} (e.g., about_{{ModuleName}}.help.md), parallel to the Public/Private/test Prefix-rename loop. - After renames, replace template-facing README.md with the now-substituted README.template.md. - Adjust the "Next steps" message to match the new flow. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 5bdf33b commit 13bee8d

3 files changed

Lines changed: 227 additions & 80 deletions

File tree

‎Initialize-Template.ps1‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -262,6 +262,31 @@ if (Test-Path -Path $templateModuleFolder) {
262262
Write-Host ' Renamed example function files' -ForegroundColor Green
263263
}
264264

265+
# Rename files in docs/en-US/ that contain {{ModuleName}} placeholder (e.g., about_{{ModuleName}}.help.md)
266+
$docsFolder = Join-Path -Path $PSScriptRoot -ChildPath 'docs\en-US'
267+
if (Test-Path -Path $docsFolder) {
268+
$docsFiles = Get-ChildItem -Path $docsFolder -File | Where-Object {
269+
$_.Name -match '\{\{ModuleName\}\}'
270+
}
271+
foreach ($file in $docsFiles) {
272+
$newName = $file.Name -replace '\{\{ModuleName\}\}', $ModuleName
273+
Rename-Item -Path $file.FullName -NewName $newName
274+
Write-Verbose "Renamed: $($file.Name) -> $newName"
275+
}
276+
if ($docsFiles) {
277+
Write-Host " Renamed docs/en-US files" -ForegroundColor Green
278+
}
279+
}
280+
281+
# Replace template-facing README.md with the module-facing README.template.md
282+
# (placeholders inside README.template.md were already substituted by the file-processing loop above)
283+
$readmeTemplate = Join-Path -Path $PSScriptRoot -ChildPath 'README.template.md'
284+
$readmePath = Join-Path -Path $PSScriptRoot -ChildPath 'README.md'
285+
if (Test-Path -Path $readmeTemplate) {
286+
Move-Item -Path $readmeTemplate -Destination $readmePath -Force
287+
Write-Host ' Generated module README.md from template' -ForegroundColor Green
288+
}
289+
265290
# Initialize Git repository if requested
266291
if (-not $NoGitInit) {
267292
$gitFolder = Join-Path -Path $PSScriptRoot -ChildPath '.git'
@@ -303,7 +328,7 @@ Write-Host '========================================' -ForegroundColor Green
303328
Write-Host ''
304329
Write-Host 'Next steps:' -ForegroundColor Cyan
305330
Write-Host " 1. Review the generated files in the $ModuleName folder"
306-
Write-Host ' 2. Update the README.md with your project details'
331+
Write-Host ' 2. Review README.md and adjust to taste'
307332
Write-Host ' 3. Add your functions to the Public/ and Private/ folders'
308333
Write-Host ' 4. Run ./build.ps1 -Task Test to verify everything works'
309334
Write-Host ' 5. Push to your GitHub repository'

‎README.md‎

Lines changed: 88 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,113 +1,122 @@
1-
# {{ModuleName}}
1+
# PowerShell Module Template
22

3-
{{Description}}
3+
A GitHub repository template for building, testing, and publishing PowerShell modules. Click **Use this template** at the top of the repo, run a one-shot init script, and you have a working module project with CI, tests, and documentation scaffolding ready to go.
44

5-
## Installation
5+
## What's included
66

7-
### From PowerShell Gallery
7+
### Build & test
88

9-
```powershell
10-
Install-Module -Name {{ModuleName}} -Scope CurrentUser
11-
```
9+
- **psake + PowerShellBuild** task pipeline (`build.ps1`, `build.psake.ps1`)
10+
- **Pester 5.x** test layout with `tests/Unit/{Public,Private}` scaffolding
11+
- **PSScriptAnalyzer** lint configuration
12+
- **Code coverage** via JaCoCo + Codecov (`codecov.yml`)
13+
- **Manifest validation tests** with SemVer-aware version-constraint checks (`tests/Manifest.tests.ps1`, `tests/ManifestHelpers.psm1`)
14+
- **Help documentation tests** that verify every public function has comment-based help with synopsis, description, and examples (`tests/Help.tests.ps1`)
15+
- **Meta tests** that catch UTF-16 files and tab indentation (`tests/Meta.tests.ps1`)
16+
- **Integration test loader** — `tests/local.settings.example.ps1` documents how to wire local secrets without committing them
1217

13-
### From Source
18+
### CI/CD (GitHub Actions)
1419

15-
```powershell
16-
git clone {{ProjectUri}}.git
17-
cd {{ModuleName}}
18-
./build.ps1 -Task Build -Bootstrap
19-
Import-Module ./Output/{{ModuleName}}/*/{{ModuleName}}.psd1
20-
```
20+
- `CI.yaml` — lint + test on push and PR
21+
- `PublishModuleToPowerShellGallery.yaml` — publish on release
22+
- `auto-merge-bots.yml` — auto-merge dependabot/pre-commit PRs
23+
- `ggshield.yaml` — secret scanning
24+
- Dependabot config and FUNDING file
2125

22-
## Requirements
26+
### Developer experience
2327

24-
- PowerShell 5.1 or later (Desktop or Core)
25-
- Windows, Linux, or macOS
28+
- **`.devcontainer/`** with Docker Compose + host setup script
29+
- **`.pre-commit-config.yaml`** with ggshield secret scanning
30+
- **`instructions/`** — 12 markdown guides for AI agents (PowerShell style, testing, releases, git workflow, etc.)
31+
- **`AGENTS.md`** — top-level AI agent guidance
32+
- Markdown linting via `.markdownlint-cli2.jsonc`
2633

27-
## Quick Start
34+
### Module scaffolding
2835

29-
```powershell
30-
# Import the module
31-
Import-Module {{ModuleName}}
32-
33-
# Get help for available commands
34-
Get-Command -Module {{ModuleName}}
36+
- Full `.psd1` manifest with PSEdition tags, license/project URIs, and PSData metadata
37+
- `.psm1` with public/private dot-source pattern
38+
- Example public function (`Get-{{Prefix}}Example`) and private helper (`Invoke-{{Prefix}}Helper`)
39+
- `docs/en-US/about_{{ModuleName}}.help.md` stub for `Get-Help about_<Module>`
3540

36-
# Example usage
37-
Get-{{Prefix}}Example -Name 'World'
38-
```
41+
## Quick start
3942

40-
## Available Commands
43+
1. Click **Use this template → Create a new repository** at the top of this repo.
44+
2. Clone your new repository locally.
45+
3. Run the initialization script:
4146

42-
| Command | Description |
43-
|---------|-------------|
44-
| `Get-{{Prefix}}Example` | Example public function |
47+
```powershell
48+
./Initialize-Template.ps1
49+
```
4550

46-
## Development
51+
You'll be prompted for module name, function prefix, author, description, and project URL. Pass them as parameters for non-interactive use:
4752

48-
### Prerequisites
53+
```powershell
54+
./Initialize-Template.ps1 `
55+
-ModuleName 'MyAwesomeModule' `
56+
-Prefix 'Mam' `
57+
-Author 'Jane Doe' `
58+
-Description 'Does awesome things' `
59+
-ProjectUri 'https://github.com/janedoe/MyAwesomeModule'
60+
```
4961

50-
- PowerShell 5.1+ or PowerShell 7+
51-
- Git
62+
4. The script substitutes placeholders, renames files, optionally runs `git init`, and bootstraps build dependencies. Delete `Initialize-Template.ps1` when done.
5263

53-
### Building
64+
## Placeholders
5465

55-
```powershell
56-
# Clone the repository
57-
git clone {{ProjectUri}}.git
58-
cd {{ModuleName}}
66+
`Initialize-Template.ps1` replaces these tokens across all `.ps1`, `.psm1`, `.psd1`, `.md`, `.json`, `.yml`, `.yaml`, `.xml`, and `.txt` files:
5967

60-
# Bootstrap dependencies and build
61-
./build.ps1 -Task Build -Bootstrap
68+
| Placeholder | Replaced with | Example |
69+
|---|---|---|
70+
| `{{ModuleName}}` | Module name | `MyAwesomeModule` |
71+
| `{{Prefix}}` | Function noun prefix | `Mam` |
72+
| `{{Author}}` | Author name | `Jane Doe` |
73+
| `{{Description}}` | Module description | `Does awesome things` |
74+
| `{{ProjectUri}}` | Repository URL | `https://github.com/...` |
75+
| `{{GUID}}` | Generated GUID | (new GUID per run) |
76+
| `{{Date}}` | ISO date at init | `2026-04-29` |
77+
| `{{Year}}` | Year at init | `2026` |
6278

63-
# Run tests
64-
./build.ps1 -Task Test
65-
```
79+
The script also renames the `{{ModuleName}}` folder, files containing `{{ModuleName}}` or `{{Prefix}}` in their names (in `Public/`, `Private/`, `tests/Unit/`, `docs/en-US/`), and replaces `README.md` with the post-init module README sourced from `README.template.md`.
6680

67-
### Project Structure
81+
## Project structure (post-init)
6882

6983
```
70-
{{ModuleName}}/
71-
├── {{ModuleName}}/ # Module source
72-
│ ├── Public/ # Exported functions
73-
│ └── Private/ # Internal helpers
74-
├── tests/ # Pester tests
75-
│ ├── Unit/ # Unit tests
76-
│ ├── Meta.tests.ps1 # Code style tests
77-
│ ├── Manifest.tests.ps1 # Manifest validation
78-
│ └── Help.tests.ps1 # Help documentation tests
79-
├── docs/ # Documentation
80-
├── .github/workflows/ # CI/CD pipelines
81-
└── build.ps1 # Build entry point
84+
<ModuleName>/
85+
├── <ModuleName>/ # Module source
86+
│ ├── Public/ # Exported functions
87+
│ └── Private/ # Internal helpers
88+
├── tests/
89+
│ ├── Unit/{Public,Private}/ # Per-function tests
90+
│ ├── Help.tests.ps1 # Comment-based-help validation
91+
│ ├── Manifest.tests.ps1 # Manifest + dependency-version validation
92+
│ ├── Meta.tests.ps1 # Encoding + indentation checks
93+
│ └── ManifestHelpers.psm1 # SemVer comparison helpers
94+
├── docs/en-US/ # platyPS help (generated)
95+
├── instructions/ # AI agent guidance (12 files)
96+
├── .github/workflows/ # CI, publish, auto-merge, secret scan
97+
├── .devcontainer/ # VS Code dev container
98+
├── build.ps1 # Build entry point
99+
├── build.psake.ps1 # psake task definitions
100+
├── build.depend.psd1 # Build/test module dependencies
101+
└── requirements.psd1 # Runtime module dependencies
82102
```
83103

84-
### Available Build Tasks
104+
## Working on the template itself
105+
106+
If you want to contribute to the template (this repo) rather than use it:
85107

86108
```powershell
87-
./build.ps1 -Help
109+
./build.ps1 -Task Test -Bootstrap
88110
```
89111

90-
| Task | Description |
91-
|------|-------------|
92-
| `Build` | Build the module to Output/ |
93-
| `Test` | Run all tests with code coverage |
94-
| `Analyze` | Run PSScriptAnalyzer |
95-
| `Pester` | Run Pester tests only |
96-
| `Clean` | Remove build artifacts |
97-
| `Publish` | Publish to PowerShell Gallery |
112+
The test suite runs against the `{{ModuleName}}` placeholder module to verify the scaffolding is sound. See [AGENTS.md](AGENTS.md) and [`instructions/`](instructions/) for contribution conventions.
98113

99-
## Contributing
114+
## Requirements
100115

101-
1. Fork the repository
102-
2. Create a feature branch
103-
3. Make your changes
104-
4. Run tests: `./build.ps1 -Task Test`
105-
5. Submit a pull request
116+
- PowerShell 5.1+ or PowerShell 7+
117+
- Git
118+
- (Optional) Docker for the devcontainer
106119

107120
## License
108121

109-
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
110-
111-
## Changelog
112-
113-
See [CHANGELOG.md](CHANGELOG.md) for version history.
122+
[MIT](LICENSE)

‎README.template.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# {{ModuleName}}
2+
3+
{{Description}}
4+
5+
## Installation
6+
7+
### From PowerShell Gallery
8+
9+
```powershell
10+
Install-Module -Name {{ModuleName}} -Scope CurrentUser
11+
```
12+
13+
### From Source
14+
15+
```powershell
16+
git clone {{ProjectUri}}.git
17+
cd {{ModuleName}}
18+
./build.ps1 -Task Build -Bootstrap
19+
Import-Module ./Output/{{ModuleName}}/*/{{ModuleName}}.psd1
20+
```
21+
22+
## Requirements
23+
24+
- PowerShell 5.1 or later (Desktop or Core)
25+
- Windows, Linux, or macOS
26+
27+
## Quick Start
28+
29+
```powershell
30+
# Import the module
31+
Import-Module {{ModuleName}}
32+
33+
# Get help for available commands
34+
Get-Command -Module {{ModuleName}}
35+
36+
# Example usage
37+
Get-{{Prefix}}Example -Name 'World'
38+
```
39+
40+
## Available Commands
41+
42+
| Command | Description |
43+
|---------|-------------|
44+
| `Get-{{Prefix}}Example` | Example public function |
45+
46+
## Development
47+
48+
### Prerequisites
49+
50+
- PowerShell 5.1+ or PowerShell 7+
51+
- Git
52+
53+
### Building
54+
55+
```powershell
56+
# Clone the repository
57+
git clone {{ProjectUri}}.git
58+
cd {{ModuleName}}
59+
60+
# Bootstrap dependencies and build
61+
./build.ps1 -Task Build -Bootstrap
62+
63+
# Run tests
64+
./build.ps1 -Task Test
65+
```
66+
67+
### Project Structure
68+
69+
```
70+
{{ModuleName}}/
71+
├── {{ModuleName}}/ # Module source
72+
│ ├── Public/ # Exported functions
73+
│ └── Private/ # Internal helpers
74+
├── tests/ # Pester tests
75+
│ ├── Unit/ # Unit tests
76+
│ ├── Meta.tests.ps1 # Code style tests
77+
│ ├── Manifest.tests.ps1 # Manifest validation
78+
│ └── Help.tests.ps1 # Help documentation tests
79+
├── docs/ # Documentation
80+
├── .github/workflows/ # CI/CD pipelines
81+
└── build.ps1 # Build entry point
82+
```
83+
84+
### Available Build Tasks
85+
86+
```powershell
87+
./build.ps1 -Help
88+
```
89+
90+
| Task | Description |
91+
|------|-------------|
92+
| `Build` | Build the module to Output/ |
93+
| `Test` | Run all tests with code coverage |
94+
| `Analyze` | Run PSScriptAnalyzer |
95+
| `Pester` | Run Pester tests only |
96+
| `Clean` | Remove build artifacts |
97+
| `Publish` | Publish to PowerShell Gallery |
98+
99+
## Contributing
100+
101+
1. Fork the repository
102+
2. Create a feature branch
103+
3. Make your changes
104+
4. Run tests: `./build.ps1 -Task Test`
105+
5. Submit a pull request
106+
107+
## License
108+
109+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
110+
111+
## Changelog
112+
113+
See [CHANGELOG.md](CHANGELOG.md) for version history.

0 commit comments

Comments
 (0)