README.md.ps1

<#
.SYNOPSIS
    README.md.ps1
.DESCRIPTION
    README.md.ps1 makes README.md

    This is a simple and helpful scripting convention for writing READMEs.

    `./README.md.ps1 > ./README.md`

    Feel free to copy and paste this code.
    
    Please document your parameters, and add NOTES.
.NOTES        
    This README.md.ps1 is used to generate help for a module.

    It:

    * Outputs the name and description
    * Provides installation instructions
    * Lists commands
    * Lists parameters
    * Lists examples
    * Lists Extended Types
.EXAMPLE
    ./README.md.ps1 > ./README.md
.EXAMPLE
    Get-Help ./README.md.ps1
#>
param(
# The name of the module     
[string]$ModuleName = $($PSScriptRoot | Split-Path -Leaf),

# The domains that serve git repositories.
# If the project uri links to this domain, 
# installation instructions will show how to import the module locally.
[string[]]
$GitDomains = @(
    'github.com', 'tangled.org', 'tangled.sh', 'codeberg.org'
),

# A list of types the module exposes
[Alias('ModuleTypeNames','ModuleTypes')]
[string[]]
$ModuleTypeName = @(
    Get-ChildItem -Path $PSScriptRoot -Filter *.types.ps1xml |
        Select-Xml /Types/Type/Name |
        Foreach-Object {$_.Node.InnerText } |
        Sort-Object 
),

# The name of the root directory containing types.
[string]
$TypeRoot = 'Types',

# If set, we don't need no badges.
[switch]
$NoBadge,

# If set, will not display gallery instructions or badges
[switch]
$NotOnGallery
)

Push-Location $PSScriptRoot

# Import the module
$module = Import-Module "./$ModuleName.psd1" -PassThru

# And output a header
"# $module"

if (-not $NoBadge) {
    # If it is on the gallery, show the downloads badge.
    if (-not $NotOnGallery) {        
        @(
            "[!"
                "[$ModuleName](https://img.shields.io/powershellgallery/dt/$ModuleName)"             
            "](https://www.powershellgallery.com/packages/$ModuleName/)"
        ) -join ''
    }    
}

# Show the module description
"## $($module.Description)"

# Show any intro section defined in the manifest
$module.PrivateData.PSData.PSIntro

#region Boilerplate installation instructions
if (-not $NotOnGallery) {
@"

## Installing and Importing

You can install $ModuleName from the [PowerShell gallery](https://powershellgallery.com/)

~~~PowerShell
Install-Module $($ModuleName) -Scope CurrentUser -Force
~~~

Once installed, you can import the module with:

~~~PowerShell
Import-Module $ModuleName -PassThru
~~~

"@
}
#endregion Gallery installation instructions

#region Git installation instructions
$projectUri = $module.PrivateData.PSData.ProjectURI -as [uri]

if ($projectUri.DnsSafeHost -in $GitDomains) {
@"

You can also clone the repo and import the module locally:

~~~PowerShell
git clone $projectUri
cd ./$ModuleName
Import-Module ./ -PassThru
~~~

"@
}
#endregion Git installation instructions

#region Exported Functions
$exportedFunctions = $module.ExportedFunctions
if ($exportedFunctions) {

    "## Functions"

    "$($ModuleName) has $($exportedFunctions.Count) function$(
        if ($exportedFunctions.Count -gt 1) { "s"}
    )"

    foreach ($export in $exportedFunctions.Keys | Sort-Object) {                
        # Get help if it there is help to get
        $help = Get-Help $export
        # If the help is a string, 
        if ($help -is [string]) {
            # make it preformatted text
            "~~~"
            "$export"
            "~~~"
        } else {
            # Otherwise, add list the export
            "### $($export)"

            # And make it's synopsis a header
            "#### $($help.SYNOPSIS)"

            # put the description below that
            "$($help.Description.text -join [Environment]::NewLine)"

            # Make a table of parameters
            if ($help.parameters.parameter) {
                "##### Parameters"

                ""                

                "|Name|Type|Description|"
                "|-|-|-|"
                foreach ($parameter in $help.Parameters.Parameter) {
                    "|$($parameter.Name)|$($parameter.type.name)|$(
                        $parameter.description.text -replace '(?>\r\n|\n)', '<br/>'
                    )|"
                }

                ""
            }
            
            # Show our examples
            "##### Examples"

            $exampleNumber = 0
            foreach ($example in $help.examples.example) {
                $markdownLines = @()
                $exampleNumber++
                $nonCommentLine = $false
                "###### Example $exampleNumber"
                
                # Combine the code and remarks
                $exampleLines = 
                    @(
                        $example.Code
                        foreach ($remark in $example.Remarks.text) {
                            if (-not $remark) { continue }
                            $remark
                        }
                    ) -join ([Environment]::NewLine) -split '(?>\r\n|\n)' # and split into lines

                # Go thru each line in the example as part of a loop
                $codeBlock = @(foreach ($exampleLine in $exampleLines) {
                    # Any comments until the first uncommentedLine are markdown
                    if ($exampleLine -match '^\#' -and -not $nonCommentLine) {
                        $markdownLines += $exampleLine -replace '^\#\s{0,1}'
                    } else {
                        $nonCommentLine = $true
                        $exampleLine
                    }
                }) -join [Environment]::NewLine

                $markdownLines
                "~~~PowerShell"
                $CodeBlock
                "~~~"
            }

            $relatedUris = foreach ($link in $help.relatedLinks.navigationLink) {
                if ($link.uri) {
                    $link.uri
                }
            }
            if ($relatedUris) {
                "#### Links"
                foreach ($related in $relatedUris) {
                    "* [$related]($related)"
                }
            }
        }
    }
}
#endregion Exported Functions

#region Exported Types
if ($ModuleTypeName) {
    $typeData = Get-TypeData -TypeName $ModuleTypeName

    if ($typeData) {
        "## Types"
    }

    foreach ($typeInfo in $typeData) {
        $memberDirectory = "./Types/$($typeInfo.TypeName)"
        if (-not (Test-Path $memberDirectory)) { continue }
        $psTypeNames = @(Get-ChildItem -Path $memberDirectory |
            Where-Object Name -match 'PSTypeNames?\.txt$' |
            Get-Content)
        if (-not $psTypeNames) {
            $psTypeNames = @($typeInfo.TypeName)
        }
        "### $($typeInfo.TypeName)"

        if ($psTypeNames.Count -gt 1) {
            "> Also Known As:"
            $psTypeNames | 
                Where-Object { $_ -ne $typeInfo.TypeName} |
                Foreach-Object { "* $_"}            
        }

        
        "#### Members"
        "|Name|MemberType|"
        "|-|-|"

        foreach ($memberName in $typeInfo.Members.Keys) {
            "|$(
                $memberPath = "./Types/$($typeInfo.TypeName)/$memberName.ps1"
                if (Test-Path $memberPath) {
                    "[$memberName]($($memberPath -replace '^\./'))"
                }                 
                else {
                    $getPath = "./Types/$($typeInfo.TypeName)/get_$memberName.ps1"
                    $setPath = "./Types/$($typeInfo.TypeName)/set_$memberName.ps1"
                    if (
                        (Test-Path $getPath) -and 
                        (Test-Path $setPath)) {
                        "[get]($(
                            $getPath -replace '^\./'
                        ))/[set]($(
                            $setPath -replace '^\./'
                        ))_[$memberName]($(
                            $getPath -replace '^\./'
                        ))"
                    } 
                    elseif (Test-Path $getPath) {
                        "[get_$memberName]($(
                            $getPath -replace '^\./'
                        ))"
                    } else {
                        $memberName
                    }                    
                }
            )|$(
                $typeInfo.Members[$memberName].GetType().Name -replace 'Data$'
            )|"
        }        
    }
}
#endregion Exported Types

#region Copyright Notice
if ($module.Copyright) {
    "> $($module.Copyright)"        
}

if ($module.PrivateData.PSData.LicenseUri) {
    ""
    "> [LICENSE]($($module.PrivateData.PSData.LicenseUri))"
}
#endregion Copyright Notice

Pop-Location