Generate-Documentation.ps1

Using module Alt3.Docusaurus.Powershell
Using module PlatyPS

Set-StrictMode -Version Latest;

# -----------------------------------------------------------------------------
# Use below settings to manipulate the rendered MDX files
# -----------------------------------------------------------------------------
$DocusaurusOptions = @{
    DocsFolder      = Resolve-Path "$PSScriptRoot/../docs/docs"
    EditUrl         = "null"
    Exclude         = @()
    MetaDescription = 'Help page for the "%1" command'
    MetaKeywords    = @('PowerShell', 'Help', 'Documentation')
}

Write-Output 'Removing existing MDX files';
$OutputFolder = $DocusaurusOptions.DocsFolder | Join-Path -ChildPath 'modules';
if (Test-Path -Path $OutputFolder) {
    Remove-Item -Path $OutputFolder -Recurse -Force;
}
$OutputFolder = $DocusaurusOptions.DocsFolder | Join-Path -ChildPath 'scripts';
if (Test-Path -Path $OutputFolder) {
    Remove-Item -Path $OutputFolder -Recurse -Force;
}
$TempFolder = Join-Path -Path ([System.IO.Path]::GetTempPath()) -ChildPath 'Alt3.Docusaurus.Powershell';
if (Test-Path -Path $TempFolder) {
    Remove-Item -Path $TempFolder -Recurse -Force;
}

# -----------------------------------------------------------------------------
# Generate the new MDX Files for each module
# -----------------------------------------------------------------------------
# TODO - Add support for scripts
$Slash = [System.IO.Path]::DirectorySeparatorChar;
$Modules = Get-ChildItem -Path "$PSScriptRoot/../src/" -Include '*.psm1' -File -Recurse |
    Where-Object { $_.FullName -notlike "*${Slash}Compiler${Slash}*" };
foreach ($Module in $Modules) {
    $ModuleDocusaurusOptions = $DocusaurusOptions.Clone();
    $ModuleDocusaurusOptions.Module = $Module.BaseName;

    $Parents = $Module.DirectoryName.Split("${Slash}src${Slash}")[1];
    $Type = $Module.Extension -eq '.psm1' ? 'module' : 'script';
    $ModuleDocusaurusOptions.SideBar = "$Type/$Parents/$($Module.BaseName)";

    Write-Output "Generating new MDX files for module: $($Module.BaseName) in $Parents";
    try {
        $Error.clear()

        try {
            Import-Module -Name $Module.FullName -Force -ErrorAction Stop;
        } catch {
            $Errs = $Error.clone();
            Write-Error "Unable to import $($Module.FullName)"
            Write-Error "Possible errors:"
            Write-Output $Errs
            continue
        }

        New-DocusaurusHelp @ModuleDocusaurusOptions;
    } catch {
        Write-Error "Failed to generate MDX files for module: $($Module.BaseName) in $Parents" -ErrorAction Continue;
        Write-Error $_ -ErrorAction Continue;
    } finally {
        Remove-Module -Name $Module.BaseName -Force -ErrorAction SilentlyContinue;
    }
}

# -----------------------------------------------------------------------------
# Generate the Sidebar file
# -----------------------------------------------------------------------------
$Sidebar = "$PSScriptRoot/../docs/sidebars.js";
@'
// @ts-check

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
  ModulesSidebar: [{type: 'autogenerated', dirName: 'modules'}],
  ScriptsSidebar: [{type: 'autogenerated', dirName: 'scripts'}],
};

export default sidebars;

'@ | Set-Content -Path $Sidebar -Force;