PSDocs

A PowerShell module with commands to generate markdown from objects using PowerShell syntax.

AppVeyor (Windows)	Codecov (Windows)

Disclaimer

This project is to be considered a proof-of-concept and not a supported Microsoft product.

Modules

The following modules are included in this repository.

Module	Description	Latest version
PSDocs	Generate markdown from PowerShell
PSDocs.Dsc	Extension for PSDocs to generate markdown from Desired State Configuration

Getting started

Prerequsits

• Windows Management Framework (WMF) 5.0 or greater
• .NET Framework 4.6 or greater

Getting the modules

• Install from PowerShell Gallery

# Install base PSDocs module
Install-Module -Name 'PSDocs';

# Optionally install DSC extensions module, which will install PSDocs if not already installed
Install-Module -Name 'PSDocs.Dsc';

• Save for offline use from PowerShell Gallery

# Save PSDocs module, in the .\modules directory
Save-Module -Name 'PSDocs' -Path '.\modules';

# Save PSDocs.Dsc module, in the .\modules directory
Save-Module -Name 'PSDocs.Dsc' -Path '.\modules';

Generate a document from a directory listing

# Import PSDocs module
Import-Module -Name PSDocs;

# Define a document called Sample
Document Sample {

    # Add an introduction section
    Section Introduction {
        # Add a comment
        "This is a sample file list from $InputObject"

        # Generate a table
        Get-ChildItem -Path $InputObject | Table -Property Name,PSIsContainer
    }
}

# Call the document definition and generate markdown from an object
Invoke-PSDocument -Name 'Sample' -InputObject 'C:\';

An example of the output generated is available here.

Generate documentation from Desired State Configuration

# Import PSDocs.Dsc module
Import-Module -Name PSDocs.Dsc;

# Define a document called Sample
Document 'Sample' {

    # Add an 'Installed features' section in the document
    Section 'Installed features' {
        # Add a comment
        'The following Windows features have been installed.'

        # Generate a table of Windows Features
        $InputObject.ResourceType.WindowsFeature | Table -Property Name,Ensure
    }
}

# Call the document definition and generate markdown for each .mof file in the .\nodes directory
Invoke-DscNodeDocument -DocumentName 'Sample' -Path '.\nodes' -OutputPath '.\docs';

Language reference

PSDocs extends PowerShell with domain specific language (DSL) keywords and cmdlets.

Keywords

The following language keywords are used by the PSDocs module:

• Document - Defines a named documentation block
• Section - Creates a named section
• Title - Sets the document title
• Code - Inserts a block of code
• Note - Inserts a note using DocFx formatted markdown (DFM)
• Warning - Inserts a warnding usinf DocFx formatted markdown (DFM)
• Yaml - Inserts a YAML header
• Table - Inserts a table from pipeline objects

Commands

The following commands exist in the PSDocs module:

• Invoke-PSDocument
• Get-PSDocumentHeader
• Import-PSDocumentTemplate

The following commands exist in the PSDocs.Dsc module:

• Get-DscMofDocument
• Invoke-DscNodeDocument

Changes and versioning

Modules in this repository will use the semantic versioning model to declare breaking changes from v1.0.0. Prior to v1.0.0, breaking changes may be introduced in minor (0.x.0) version increments. For a list of module changes please see the change log.

Maintainers

• Bernie White

License

This project is licensed under the MIT License.