Giter VIP home page Giter VIP logo

ps-reptile's Introduction

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 (Microsoft Assistance Markup Language) format. If, like me, you think this sounds incredibly tedious, 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)

[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)

[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

/// <summary>Retrieve information about one or more Foo connection profiles.</summary>
[Cmdlet(VerbsCommon.Get, "Foo")]
[OutputType(typeof(FooConnectionProfile))]
public class GetFooConnection
{
    /// <summary>Retrieve all connection profiles.</summary>
    [Parameter]
    public SwitchParameter All { get; set; }
}

Mix-and-match example

/// <summary>Retrieve information about one or more Foo connection profiles.</summary>
[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.

ps-reptile's People

Contributors

tintoy avatar

Stargazers

 avatar  avatar

Watchers

 avatar  avatar

ps-reptile's Issues

Usage

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.

Expected a closing quote in PSReptile.Build.targets(10,9)

After adding a reference to PSReptile.Build I get the following error when building my project:

C:\Users\nlowe\.nuget\packages\psreptile.build\0.0.2-alpha1\build\PSReptile.Build.targets(10,9): error MSB4101: Expected a closing quote after position 29 in condition " '$(BuildPSHelp)' == 'true' '". [C:\Users\nlowe\Projects\Harbor.PowerShell\src\Harbor.PowerShell\Harbor.PowerShell.csproj]

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

Looks like you have an extra quote:

Condition=" '$(BuildPSHelp)' == 'true' '"

I believe it should be:

Condition=" '$(BuildPSHelp)' == 'true' "

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.