diff --git a/.github/workflows/pre-release.yaml b/.github/workflows/pre-release.yaml index 8ce1fe76..c6fc7cd9 100644 --- a/.github/workflows/pre-release.yaml +++ b/.github/workflows/pre-release.yaml @@ -16,6 +16,25 @@ jobs: - name: Checkout Repository uses: actions/checkout@v6 + - name: Generate Dev Docs and Update JSON Links + shell: pwsh + run: | + Set-Location tools + ./devdocs-generator.ps1 + + - name: Commit Updated JSON Links + shell: pwsh + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + git add config/tweaks.json config/feature.json + $changes = git diff --cached --quiet; if ($LASTEXITCODE -ne 0) { + git commit -m "Update documentation links in JSON configs" + git push + } else { + Write-Host "No JSON link changes to commit" + } + - name: Compile project shell: pwsh run: | diff --git a/docs/i18n/en.yaml b/docs/i18n/en.yaml index 8d11d08a..38c617fb 100644 --- a/docs/i18n/en.yaml +++ b/docs/i18n/en.yaml @@ -1,4 +1,4 @@ -copyright: "© Chris Titus Tech. All rights reserved." +copyright: "©   Chris Titus Tech. All rights reserved." backToTop: "Scroll to top" changeLanguage: "Change language" diff --git a/tools/devdocs-generator.md b/tools/devdocs-generator.md new file mode 100644 index 00000000..fd04129a --- /dev/null +++ b/tools/devdocs-generator.md @@ -0,0 +1,100 @@ +--- +title: "Dev Docs Generator" +description: "How the devdocs-generator.ps1 script works" +--- + +# Dev Docs Generator + +The `devdocs-generator.ps1` script automatically generates Hugo-compatible markdown files for the development documentation. It pulls content directly from the JSON config files and PowerShell function files so the docs never go out of sync. + +## When Does It Run? + +- Automatically in CI via the GitHub Actions `docs.yaml` workflow before Hugo builds the site +- Triggered when any of these change: `docs/**`, `config/tweaks.json`, `config/feature.json`, `functions/**` +- Can also be run manually with `workflow_dispatch` + +## What Does It Do? + +### 1. Loads the Data + +- Reads `config/tweaks.json` and `config/feature.json` +- Reads all `.ps1` function files from `functions/public/` and `functions/private/` +- Parses `Invoke-WPFButton.ps1` to build a mapping of button names to their function names + +### 2. Updates Links in JSON + +- Adds or updates a `"link"` property on every entry in both JSON config files +- Each link points to that entry's documentation page on the Hugo site + +### 3. Cleans Up Old Docs + +- Deletes all `.md` files (except `_index.md`) from `docs/content/dev/tweaks/` and `docs/content/dev/features/` +- This prevents duplicate or orphaned files from previous runs + +### 4. Generates Tweak Documentation + +For each entry in `tweaks.json` that belongs to a documented category: + +- **Button type** entries get the mapped PowerShell function file embedded +- **All other types** get the raw JSON snippet embedded with correct line numbers from the source file +- Entries with **registry changes** get a Registry Changes section added +- Entries with **services** get the `Set-WinUtilService.ps1` function appended + +### 5. Generates Feature Documentation + +For each entry in `feature.json` that belongs to a documented category: + +- **Fixes and Legacy Windows Panels** get the mapped PowerShell function file embedded +- **Features** get the raw JSON snippet embedded with correct line numbers + +### 6. Output Format + +- Every `.md` file gets Hugo frontmatter with `title` and `description` +- Code blocks use Hugo syntax with filename labels and line numbers +- Files are organized into category subdirectories matching the JSON `category` field + +## Documented Categories + +The script generates docs for entries in these categories: + +- Essential Tweaks +- z__Advanced Tweaks - CAUTION +- Customize Preferences +- Performance Plans +- Features +- Fixes +- Legacy Windows Panels + +## File Structure + +``` +docs/content/dev/ + tweaks/ + Essential-Tweaks/ + z--Advanced-Tweaks---CAUTION/ + Customize-Preferences/ + Performance-Plans/ + features/ + Features/ + Fixes/ + Legacy-Windows-Panels/ +``` + +## How File Names Are Derived + +The script strips common prefixes from the JSON key names using the pattern `WPF(WinUtil|Toggle|Features?|Tweaks?|Panel|Fix(es)?)?`. For example: + +| JSON Key | Generated File | +|---|---| +| `WPFTweaksHiber` | `Hiber.md` | +| `WPFTweaksDeBloat` | `DeBloat.md` | +| `WPFFeatureshyperv` | `hyperv.md` | +| `WPFPanelDISM` | `DISM.md` | + +## Key Points + +- The JSON config files are the single source of truth +- Manual edits to generated `.md` files will be overwritten on the next run +- The script does not touch `_index.md` files or `architecture.md` +- Category directories are created automatically if they don't exist +- The `"link"` property added to JSON entries is excluded from the displayed code blocks diff --git a/tools/devdocs-generator.ps1 b/tools/devdocs-generator.ps1 index 955838be..9b384b6b 100644 --- a/tools/devdocs-generator.ps1 +++ b/tools/devdocs-generator.ps1 @@ -242,7 +242,7 @@ foreach ($itemName in $tweakNames) { # Hugo frontmatter $title = $item.Content -replace '"', '\"' - $content = "---`r`ntitle: `"$title`"`r`ndescription: `"`"`r`n---`r`n" + $content = "---`r`ntitle: `"$title`"`r`ndescription: `"`"`r`n---`r`n`r`n" if ($item.Type -eq "Button") { # Button-type tweak: embed the mapped PowerShell function @@ -315,7 +315,7 @@ foreach ($itemName in $featureNames) { } $title = $item.Content -replace '"', '\"' - $content = "---`r`ntitle: `"$title`"`r`ndescription: `"`"`r`n---`r`n" + $content = "---`r`ntitle: `"$title`"`r`ndescription: `"`"`r`n---`r`n`r`n" if ($item.category -eq "Fixes" -or $item.category -eq "Legacy Windows Panels") { # Embed the PowerShell function file