docs: generate and enforce reference documentation from code (#25)

[blindzero]

Summary

This PR introduces automatic generation of reference documentation from the current codebase and enforces it via CI to prevent documentation drift.

What’s included

• Cmdlet Reference generation (platyPS-based)
  • Generator: tools/Generate-IdleCmdletReference.ps1
  • Output:
    • docs/reference/cmdlets.md (index with synopsis table)
    • docs/reference/cmdlets/*.md (one file per cmdlet)
• Step Catalog generation
  • Generator: tools/Generate-IdleStepReference.ps1
  • Output: docs/reference/steps.md
• Documentation wiring
  • Links added to docs/index.md
  • Contributor workflow documented in CONTRIBUTING.md (including CI behavior)
• CI enforcement
  • CI verifies both generated references are up to date by running the generators and failing if git diff is not clean.

Why

• Keeps reference docs accurate and always aligned with the exported cmdlets and built-in steps.
• Reduces contributor burden and review friction.
• Improves Developer UX (“batteries included”) without changing runtime behavior.

How to regenerate locally

From repo root:

pwsh ./tools/Generate-IdleCmdletReference.ps1
pwsh ./tools/Generate-IdleStepReference.ps1

If platyPS is missing (first time):

pwsh ./tools/Generate-IdleCmdletReference.ps1 -InstallPlatyPS

How to test

• Run generators locally and ensure no diff is produced afterwards:

pwsh ./tools/Generate-IdleCmdletReference.ps1
pwsh ./tools/Generate-IdleStepReference.ps1
git diff --exit-code

• CI should run the verification jobs and stay green.

Notes

• Generated docs under docs/reference/ are not meant to be edited by hand; update comment-based help / step sources and regenerate.

Issues

Fixes Closes #25

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".