Improve Wiki Generation - Automatically Add Examples to Appropriate Resource Page

[PlagueHO]

Examples sometimes need to appear in multiple resources README.MD in wiki auto-generation repos. To do this currently the same example is stored multiple times in the repo.

From @johlju - dsccommunity/DFSDsc#64 (comment)

I seeing those examples being in the root of the Examples folder, and logic that checks each file (AST?) if that particular resource is present, then adds a link (maybe .SYNOPSIS as descriptive text) from the resource Wiki page to the "example Wiki page". On Home-page there can be Example section with all the "general" examples that links to each "example Wiki page".

[johlju]

Maybe we can use the .LINK keyword in the comment-based help for this. Each linked item will get a link to the example from the resource documentation page.

Also I don't think we should use .EXAMPLE keyword to write the description under. It renders wrong when shown with Get-Help.

    -------------------------- EXAMPLE 1 --------------------------

    PS C:\>Create a Hub and Spoke style DFS Replication Group called WebSite

    containing one Hub member and one or more Spoke members. The name of
    the Hub computer is passed in the HubComputerName parameter and
    defaults to 'Hub'. The Hub member contains a folder called WebSiteFiles
    with the path 'd:\inetpub\wwwroot\WebSiteFiles'. This path is
    replicated to all members of the SpokeComputerName parameter array
    into the 'd:\inetpub\wwwroot\WebSiteFiles' folder. The spoke
    computers are passed in the SpokeComputerName parameter and
    defaults to 'Spoke1', 'Spoke2' and 'Spoke3'.

So maybe Example files should have a comment block like this. Maybe .EXAMPLE can be skipped entierly.

<#
    .SYNOPSIS
        Create a Hub and Spoke style DFS Replication Group

    .DESCRIPTION
        Create a Hub and Spoke style DFS Replication Group called WebSite
        containing one Hub member and one or more Spoke members. The name of
        the Hub computer is passed in the HubComputerName parameter and
        defaults to 'Hub'. The Hub member contains a folder called WebSiteFiles
        with the path 'd:\inetpub\wwwroot\WebSiteFiles'. This path is
        replicated to all members of the SpokeComputerName parameter array
        into the 'd:\inetpub\wwwroot\WebSiteFiles' folder. The spoke
        computers are passed in the SpokeComputerName parameter and
        defaults to 'Spoke1', 'Spoke2' and 'Spoke3'.

    .EXAMPLE
        Example -OutputPath $env:TEMP

        Compiles the configuration and saves it into the temp folder.

    .LINK
        DFSReplicationGroup

    .LINK
        DFSReplicationGroupFolder

    .LINK
        DFSReplicationGroupMembership

    .LINK
        DFSReplicationGroupConnection
#>

This renders like this (using Get-Help -Path <path> -Full)

NAME
    C:\Source\_Random\Comment-based_help.ps1

SYNOPSIS
    Create a Hub and Spoke style DFS Replication Group


SYNTAX
    C:\Source\_Random\Comment-based_help.ps1 [<CommonParameters>]

DESCRIPTION
    Create a Hub and Spoke style DFS Replication Group called WebSite
    containing one Hub member and one or more Spoke members. The name of
    the Hub computer is passed in the HubComputerName parameter and
    defaults to 'Hub'. The Hub member contains a folder called WebSiteFiles
    with the path 'd:\inetpub\wwwroot\WebSiteFiles'. This path is
    replicated to all members of the SpokeComputerName parameter array
    into the 'd:\inetpub\wwwroot\WebSiteFiles' folder. The spoke
    computers are passed in the SpokeComputerName parameter and
    defaults to 'Spoke1', 'Spoke2' and 'Spoke3'.

PARAMETERS
    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).

INPUTS

OUTPUTS

    -------------------------- EXAMPLE 1 --------------------------

    PS C:\>Example -OutputPath $env:TEMP

    Compiles the configuration and saves it into the temp folder.

RELATED LINKS
    DFSReplicationGroup
    DFSReplicationGroupFolder
    DFSReplicationGroupMembership
    DFSReplicationGroupConnection

[PlagueHO]

This definitely has some promise. I think we could support the current method (without linking) and the new method at the same time so that there could be a transition period (as it would require a bit of work in each repo to convert over).

So I'd propose making this change and in such a way that each repo could opt-in to this new auto documentation method once the content was in the newer format.

I'm happy to look at doing this over the weekend.

[johlju]

Agree that the transition should be opt-in if we can't do it seamless, like if .LINK exist in comment-based help then that is used instead of the old method (without opt-in). Though, that will fail if there are any existing comment-based help with .LINK with the wrong content. Opt-in works for me.
Awesome if you have time to look at this. 🙂

[PlagueHO]

I've had a think about this and I do think I could probably make it "auto-detect" with-out using the opt-in. So I'll give this a go over the weekend (makes a change from just creating and reviewing resources 😁)

[johlju]

I know what you mean 😁

[PlagueHO]

Forgot about this one! Looks like I'll need to get it sorted before I can use the publish examples! Try today/tomorrow.