Usage

[tibmeister]

Can you provide a little more detail on how to utilize this? I don't know how to run design time packages in VS2017 to be honest.

[tintoy]

Hi - from memory (sorry, it's been a while), all you need to do is add the PSReptile.Build package to the project that produces your PowerShell module and then build the project (the help file will be automatically generated). This is because the following 2 files (and their properties / targets) get automatically imported into your project when you install the package:

https://github.com/tintoy/ps-reptile/blob/master/src/PSReptile.Build/build/PSReptile.Build.props
https://github.com/tintoy/ps-reptile/blob/master/src/PSReptile.Build/build/PSReptile.Build.targets

If you want to copy the help file elsewhere (or otherwise use it during the build), it's added to an item group called PSModuleHelp.

[tintoy]

Having re-read your question, I think perhaps I didn't really answer it properly so I'll have another go :)

To add a design-time package, you install it the same way as you install any other NuGet package (Install-Package PSReptile.Build from the package management console or via the NuGet GUI).

[tintoy]

BTW, this project works just fine (and I'm happy to help if you still want to use it) but you might be interested to know that there's now an official toolchain for producing help for PowerShell modules:

https://github.com/PowerShell/platyPS

[trondr]

platyPS as you suggest as replacement for ps-reptile do not seem to support xml doc (inline xml doc in the code)? I think code and documentation should stay in the same place as it is then easier to keep code and documentation in synch. So in my opinion PS-Reptile is on the right track even if I did not get it to work in my .NET5.0 F# binary project. I have a .NET 5 F# binary that I wanted to generate maml from. I created a fork of ps-reptile project to add .NET 5 support. But when I ran the dotnet-reptile.exe on a library with the following F# code it created unsupported MAML. At least PowerShell refused to understand and show me the documentation, so I assume it was unsupported MAML. I think PS-Reptile do not support this way of documenting cmdlets?

namespace OsmPowerCli.Library.CmdLets

open System.Management.Automation
open OsmPowerCli.Library.OsmData

/// <summary>
/// <para type="synopsis">Get OSM map</para>
/// <para type="description">Get OSM map defined by "rectangular" area defined by minimum longitude/lattitude and maximum longitude/lattitude</para>
/// <example>
///     <code>Get-OsmMap -MinLongitude 10.1554 -MinLattitude 59.7368 -MaxLongitude 10.2276 -MaxLattitude 59.7448</code>
/// </example>
/// </summary>
[<Cmdlet(VerbsCommon.Get,"OsmMap")>]
[<OutputType(typeof<string>)>]
type GetOsmMapCommand () =
    inherit PSCmdlet ()
    
    /// <summary>
    /// <para type="description">Minimum longitude of the map.</para>
    /// </summary>
    [<Parameter(Mandatory=true)>]
    member val MinLongitude :float = 0.0 with get,set
    
    /// <summary>
    /// <para type="description">Minimum lattitude of the map.</para>
    /// </summary>
    [<Parameter(Mandatory=true)>]
    member val MinLattitude :float = 0.0 with get,set
    
    /// <summary>
    /// <para type="description">Maximum longitude of the map.</para>
    /// </summary>
    [<Parameter(Mandatory=true)>]
    member val MaxLongitude :float = 0.0 with get,set
    
    /// <summary>
    /// <para type="description">Maximum lattitude of the map.</para>
    /// </summary>
    [<Parameter(Mandatory=true)>]
    member val MaxLattitude :float = 0.0 with get,set
    
    override this.ProcessRecord() =
        let bounds = {
            MinLongitude = this.MinLongitude
            MinLattidue = this.MinLattitude
            MaxLongitude = this.MaxLongitude
            MaxLattitude = this.MaxLattitude
        }
        let osmMap = OsmPowerCli.Library.OsmData.getOsmMap bounds
        this.WriteObject(osmMap)
        ()

Anyway, before trying PS-Reptile I tried XmlDoc2CmdletDoc which also failed to run on my .NET 5 F# project. But I went back and forked XmlDoc2CmdletDoc and added support for .NET5. This time it worked! XmlDoc2CmdletDoc is able to create MAML from F# binaries (after manually adding Fsharp.Core.dll to the same directory as the XmlDoc2CmdletDoc.exe). So I think instead of platyPS a replacement for ps-reptile would be XmlDoc2CmdletDoc. If the maintainer of https://github.com/red-gate/XmlDoc2CmdletDoc approves the '.NET5' pull request. Until then I have released binaries for XmlDoc2CmdletDoc.exe here: https://github.com/trondr/XmlDoc2CmdletDoc/releases if this is of interest to anyone who is reading this.

[tintoy]

Hi - thanks for sharing, I'm glad you've found a solution that works for you! 🙂