• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    迪恩网络公众号

PowerShell/platyPS: Write PowerShell External Help in Markdown

原作者: [db:作者] 来自: 网络 收藏 邀请

开源软件名称(OpenSource Name):

PowerShell/platyPS

开源软件地址(OpenSource Url):

https://github.com/PowerShell/platyPS

开源编程语言(OpenSource Language):

C# 55.0%

开源软件介绍(OpenSource Introduction):

Build status Build status

Join the chat at https://gitter.im/PowerShell/platyPS

PlatyPS

PlatyPS provides a way to:

  • Write PowerShell External Help in Markdown
  • Generate markdown help (example) for your existing modules
  • Keep markdown help up-to-date with your code

Markdown help docs can be generated from old external help files (also known as MAML-xml help), the command objects (reflection), or both.

PlatyPS can also generate cab files for Update-Help.

Why?

Traditionally PowerShell external help files have been authored by hand or using complex tool chains and rendered as MAML XML for use as console help. MAML is cumbersome to edit by hand, and common tools and editors don't support it for complex scenarios like they do with Markdown. PlatyPS is provided as a solution for allow documenting PowerShell help in any editor or tool that supports Markdown.

An additional challenge PlatyPS tackles, is to handle PowerShell documentation for complex scenarios (e.g. very large, closed source, and/or C#/binary modules) where it may be desirable to have documentation abstracted away from the codebase. PlatyPS does not need source access to generate documentation.

Markdown is designed to be human-readable, without rendering. This makes writing and editing easy and efficient. Many editors support it (Visual Studio Code, Sublime Text, etc), and many tools and collaboration platforms (GitHub, Visual Studio Online) render the Markdown nicely.

Common setups

There are 2 common setups that are used:

  1. Use markdown as the source of truth and remove other types of help.
  2. Keep comment based help as the source of truth and periodically generate markdown for web-site publishing.

They both have advantages and use-cases, you should decide what's right for you. There is slight preference toward number 1 (markdown as the source).

Quick start

Install-Module -Name platyPS -Scope CurrentUser
Import-Module platyPS
  • Create initial Markdown help for MyAwesomeModule module:
# you should have module imported in the session
Import-Module MyAwesomeModule
New-MarkdownHelp -Module MyAwesomeModule -OutputFolder .\docs
  • Edit markdown files in .\docs folder and populate {{ ... }} placeholders with missed help content.

  • Create external help from markdown help

New-ExternalHelp .\docs -OutputPath en-US\
  • Congratulations, your help is now in markdown!

  • Now, if your module code changes, you can easily update your markdown help with

# re-import your module with latest changes
Import-Module MyAwesomeModule -Force
Update-MarkdownHelp .\docs

PlatyPS markdown schema

Unfortunately, you cannot just write any Markdown, as platyPS expects Markdown to be authored in a particular way. We have defined a schema to determine how parameters are described, where scripts examples are shown, and so on.

The schema closely resembles the existing output format of the Get-Help cmdlet in PowerShell.

If you break the schema in your markdown, you will get error messages from New-ExternalHelp and Update-MarkdownHelp. You would not be able to generate extrenal help or update your markdown.

It may be fine for some scenarios, i.e. you want to have online-only version of markdown.

Usage

Supported scenarios:

  • Create Markdown

    • Using existing external help files (MAML schema, XML).
    • Using reflection
    • Using reflection and existing internal external help files.
    • For a single cmdlet
    • For an entire module
  • Update existing Markdown through reflection.

  • Create a module page .md with summary. It will also allow you to create updatable help cab.

  • Retrieve markdown metadata from markdown file.

  • Create external help xml files (MAML) from platyPS Markdown.

  • Create external help file cab

  • Preview help from generated maml file.

Remoting

PlatyPS supports working with Import-PSSession aka implicit remoting. Just pass -Session $Session parameter to the platyPS cmdlets and it will do the rest.

Build

For information about building from sources and contributing see contributing guidelines.




鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
热门推荐
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap