https://github.com/tintoy/ps-reptile

A MAML-format help generator for binary PowerShell modules.
https://github.com/tintoy/ps-reptile

maml powershell powershell-help

Last synced: about 2 months ago
JSON representation

A MAML-format help generator for binary PowerShell modules.

• Host: GitHub
• URL: https://github.com/tintoy/ps-reptile
• Owner: tintoy
• License: mit
• Created: 2017-02-19T23:46:53.000Z (almost 8 years ago)
• Default Branch: master
• Last Pushed: 2017-12-27T17:35:27.000Z (about 7 years ago)
• Last Synced: 2024-11-09T01:09:36.755Z (2 months ago)
• Topics: maml, powershell, powershell-help
• Language: C#
• Size: 54.7 KB
• Stars: 2
• Watchers: 2
• Forks: 5
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# PS-Reptile (a MAML generator for binary PowerShell modules)

Unlike script modules, authoring help content for binary modules often involves manually authoring a `.xml` help file in [MAML](https://en.wikipedia.org/wiki/Microsoft_Assistance_Markup_Language) (Microsoft Assistance Markup Language) format.

If, like me, you think this [sounds incredibly tedious](https://msdn.microsoft.com/en-us/library/bb525433.aspx#code-snippet-1), then perhaps this tool will be useful. It examines the primary assembly for a binary module (and, optionally, its XML documentation comments) and generates the corresponding MAML help content.

## Custom attribute example 1 (inline help)

```csharp

[Cmdlet(VerbsCommon.Get, "Foo")]

[OutputType(typeof(FooConnectionProfile))]

[CmdletHelp("Retrieve information about one or more Foo connection profiles.")]

public class GetFooConnection

{

    [Parameter(HelpMessage = "Retrieve all connection profiles")]

    public SwitchParameter All { get; set; }

}

```

## Custom attribute example 1 (inline help)

```csharp

[Cmdlet(VerbsCommon.Get, "Foo")]

[OutputType(typeof(FooConnectionProfile))]

[CmdletHelp(

    Synopsis = "Retrieve information about one or more Foo connection profiles",

    Description = @"

        This Cmdlet retrieves information about Foo connection profiles.

        The connection profiles are persisted in $HOME/.foo/connection-profiles.json.

    "

)]

public class GetFooConnection

{

    [Parameter]

    [ParameterHelpFromFile("Help/Connections/Get-FooConnection/All.txt")]

    public SwitchParameter All { get; set; }

}

```

## XML documentation comments example

```csharp

/// Retrieve information about one or more Foo connection profiles.

[Cmdlet(VerbsCommon.Get, "Foo")]

[OutputType(typeof(FooConnectionProfile))]

public class GetFooConnection

{

    /// Retrieve all connection profiles.

    [Parameter]

    public SwitchParameter All { get; set; }

}

```

## Mix-and-match example

```csharp

/// Retrieve information about one or more Foo connection profiles.

[Cmdlet(VerbsCommon.Get, "Foo")]

[OutputType(typeof(FooConnectionProfile))]

public class GetFooConnection

{

    [Parameter(HelpMessage = "Retrieve all connection profiles")]

    public SwitchParameter All { get; set; }

}

```

# Usage

Install package `PSReptile` into your project; it contains only attribute definitions that you can apply to your Cmdlets. The generator is part of the `PSReptile.Generator` package, or just add `PSReptile.Build` as a design-time package to automatically generate help when you build your project.

# Notes

This project is very much a work-in-progress:

* If you have questions or comments, feel free to raise an issue.

* If you'd like to pitch in, any and all assistence will be greatly appreciated :-)

Eventually, we'll also implement a `dotnet` command-line plugin to invoke this tool.