documentation-generation

name

documentation-generation

description

Auto-generate documentation for PowerShell scripts, modules, and folders in the UserAdminModule repository. USE FOR: generating README files for folders that lack them, creating function catalogs from comment-based help, building module walkthroughs from script metadata, regenerating the UserAdminModule FunctionIndex, generating module documentation with PlatyPS, creating folder inventory summaries, producing dependency maps, and documenting script parameters and usage examples. DO NOT USE FOR: writing PowerShell functions (use default agent or useradminmodule skill), creating change requests (use change-request skill), or managing GitHub settings (use github-management skill).

Documentation Generation Skill

Purpose

Auto-generate consistent documentation for the UserAdminModule repository — folder READMEs, function catalogs, module indexes, and help files — by extracting metadata from existing PowerShell scripts and comment-based help blocks.

When This Skill Applies

Activate when the user:

• Asks to "generate a README", "document this folder", or "create documentation"
• Wants a "function catalog", "function index", or "module inventory"
• Asks to "regenerate the FunctionIndex" or update module documentation
• Mentions "PlatyPS", "external help", or "MAML help files"
• Wants to document what scripts exist in a folder and what they do
• Asks for a "dependency map", "module diagram", or "architecture overview"
• Wants to create or update scenario walkthroughs or guides
• Asks about documentation coverage across the repo

Repository Documentation Context

Property	Value
README coverage	Sparse — Public/ and Shell/Public/ folders lack READMEs
Auto-generated index	FunctionIndex.md and FunctionIndex.json at repo root
Index generator	Invoke-FunctionIndexRegeneration (Public/ function)
PlatyPS status	Referenced in AGENTS.md as future goal — not yet implemented
Documentation formats	Markdown (primary), HTML (ModuleMenuApp.html)
Root README	Present — README.md at repo root

---

Workflow 1 — Generate a Folder README

When to Use

User asks to document a folder, or a folder is identified as lacking a README.

Steps

1. List all scripts in the folder — Get .ps1, .psm1, .psd1 files
2. Extract metadata from each script:
   • .SYNOPSIS from comment-based help
   • .DESCRIPTION if synopsis is missing
   • Parameter list (names, types, mandatory status)
   • Required modules (#Requires -Module)
   • Required version (#Requires -Version)
3. Identify dependencies — What modules or functions does the folder import?
4. Generate the README using the template below

Folder README Template

# {FolderName}

{One-paragraph description of what this folder contains and why it exists.}

## Prerequisites

- PowerShell {version}+
- {Required modules listed}
- {Required access/permissions}

## Scripts

| Script | Description |
|--------|-------------|
| [{FileName}]({FileName}) | {Synopsis extracted from comment-based help} |
| [{FileName2}]({FileName2}) | {Synopsis} |

## Usage

### {ScriptName}

```powershell
# {Example extracted from .EXAMPLE block}
{Verb}-{Noun} -Parameter 'Value'

Dependencies

• Modules: {list of required modules}
• Functions: {list of dot-sourced functions from Functions/ or other locations}
• Permissions: {administrative requirements}

Related

• {Related folder or module}
• {Related documentation}

---

Auto-generated by UserAdminModule documentation skill. Last updated: {date}.

### Metadata Extraction Procedure

To extract metadata from a PowerShell script for documentation:

1. Read the file content
2. Look for comment-based help block (<# ... #>)
3. Extract .SYNOPSIS — first non-blank line after .SYNOPSIS tag
4. Extract .DESCRIPTION — all lines between .DESCRIPTION and next . tag
5. Extract .PARAMETER blocks — name from tag, description from body
6. Extract .EXAMPLE blocks — code and description
7. Look for #Requires statements at file top
8. Look for Import-Module or dot-source (. $PSScriptRoot...) lines
9. Look for function definitions (function Verb-Noun {)

If a script lacks comment-based help:
- Use the filename as the description basis
- Flag it as "undocumented" in the README
- Recommend adding help to the script

---

## Workflow 2 — Generate a Function Catalog

### When to Use

User asks for a catalog or index of functions in a module, folder, or the entire repo.

### Steps

1. **Determine scope** — Single submodule, all of UserAdminModule, Functions/ folder, or full repo
2. **Scan for function definitions** — Find `function Verb-Noun {` patterns
3. **Extract help metadata** — Synopsis, Description, Parameters
4. **Group by category** — Submodule name, folder, or domain
5. **Generate dual output** — Markdown (human-readable) and JSON (machine-readable)

### Function Catalog Markdown Format

Follow the established `FunctionIndex.md` pattern:

```markdown
# {Scope} Function Index

Generated: {yyyy-MM-dd HH:mm:ss} UTC

## Summary

| Category | Count | Link |
|----------|-------|------|
| {Category1} | {count} | [Jump](#{category1-anchor}) |
| {Category2} | {count} | [Jump](#{category2-anchor}) |
| **Total** | **{total}** | |

---

## {Category1}

{One-sentence description of this category's purpose.}

### {Category1} Functions

- [{FunctionName}](#{function-anchor})

---

### {FunctionName}

**Synopsis:** {extracted .SYNOPSIS}

**Description:** {extracted .DESCRIPTION}

**Source:** `{relative/path/to/file.ps1}`

[Back to {Category1}](#{category1-anchor})

Function Catalog JSON Format

[
    {
        "Category": "{CategoryName}",
        "Description": "{Category description}",
        "Functions": [
            {
                "Name": "{FunctionName}",
                "Synopsis": "{extracted synopsis}",
                "Description": "{extracted description}",
                "Source": "{relative/path/to/file.ps1}",
                "Parameters": [
                    {
                        "Name": "{ParamName}",
                        "Type": "{string|int|switch}",
                        "Mandatory": true
                    }
                ]
            }
        ]
    }
]

---

Workflow 3 — Generate Module Walkthrough

When to Use

User asks to document a module subfolder (e.g., Shell/Public/, Public/, Private/).

Steps

1. Survey the folder — List all .ps1 files
2. Extract per-function metadata — Synopsis, parameters, dependencies
3. Identify the purpose — Read Shell.psm1 or UserAdminModule.psm1 for context
4. Generate a walkthrough with prerequisites, function listing, and examples

Module Walkthrough Template

# {FolderName} — Overview

## Purpose

{Description of what this folder's functions do and when they are loaded.}

## Functions

| Function | Synopsis |
|----------|----------|
| [{FunctionName}]({FunctionName}.ps1) | {synopsis} |

## Prerequisites

| Requirement | Details |
|---|---|
| **PowerShell version** | 5.1+ and 7+ |
| **Module** | `UserAdminModule` (loaded automatically) |

## Usage Examples

### {FunctionName}

```powershell
{Example from .EXAMPLE block}

---

## Workflow 4 — Regenerate UserAdminModule FunctionIndex

### When to Use

User asks to update or regenerate the function index after adding/removing functions.

### Steps

1. **Run the existing regeneration function:**
   ```powershell
   Import-Module .\UserAdminModule.psd1 -Force
   Invoke-FunctionIndexRegeneration

2. Verify the output:
   • Check UserAdminModule/FunctionIndex.md has updated counts
   • Check UserAdminModule/FunctionIndex.json is valid JSON
   • Verify the "Generated:" timestamp is current
3. Report changes — Summarise which categories changed and by how much

Note: Prefer running the existing script over generating the index manually. The script handles all 27 submodules, category descriptions, and anchor-link generation consistently.

---

Workflow 5 — Documentation Coverage Audit

When to Use

User asks about documentation coverage or wants to know which folders need READMEs.

Steps

1. Scan all first-level folders under the repo root
2. Check for README.md (or README.txt) in each
3. Check for comment-based help in .ps1 files (presence of <# ... .SYNOPSIS)
4. Generate a coverage report:

## Documentation Coverage Report

Generated: {date}

### Folder README Coverage

| Folder | Has README | Script Count | Help Coverage |
|--------|------------|-------------|---------------|
| Public/ | No | 5 | 100% (5/5) |
| Shell/Public/ | No | 16 | 80% |
| Private/ | No | 1 | 100% (1/1) |

### Priority Recommendations

1. **{Folder}** — {count} scripts, 0% help coverage, no README
2. **{Folder}** — {count} scripts, used frequently, no README
3. ...

---

Comment-Based Help Template

When a script lacks help and needs it added:

<#
.SYNOPSIS
    {One-line summary — what the script does.}

.DESCRIPTION
    {Detailed description — purpose, behaviour, prerequisites, and output.}

    Reference: {URL to relevant Microsoft documentation}

.PARAMETER {Name}
    {Description of the parameter.}

.EXAMPLE
    .\{ScriptName}.ps1 -Parameter 'Value'

    {What this example does.}

.NOTES
    Author:     Luke Leigh
    Created:    {date}
    Requires:   {dependencies}

    Reference: {URL to Microsoft docs}

.LINK
    {Related script or documentation URL}
#>

---

Conventions — Non-Negotiable

1. Markdown format — All generated documentation must be valid Markdown
2. Relative links — Use relative paths for all intra-repo links ([file](./file.ps1))
3. Auto-generated marker — Include "Auto-generated by UserAdminModule documentation skill" footer
4. UTC timestamps — Use yyyy-MM-dd HH:mm:ss UTC format for "Generated:" lines
5. Alphabetical ordering — Functions and categories listed alphabetically
6. No fabrication — Only document what exists in files; never invent synopses
7. Flag gaps — Explicitly mark undocumented scripts as "Undocumented — help needed"
8. Preserve existing — Never overwrite manually-authored documentation; merge or append

Quality Checks

Before presenting documentation, verify:

• All file links use relative paths and point to existing files
• Function names match actual function definitions in the source
• Synopses are extracted from source (not fabricated)
• Categories match the actual folder structure
• Counts are accurate
• Undocumented scripts are flagged, not skipped
• Generated timestamp reflects actual generation time
• Auto-generated footer is present
• Markdown renders correctly (proper heading levels, table alignment)
• No hardcoded absolute paths in documentation