PowerShell MAML ヘルプ ジェネレーター

StackOverflow https://stackoverflow.com/questions/2367333

  •  23-09-2019
  •  | 
  •  

質問

PowerShell コマンドレットのヘルプ ファイルを生成するユーティリティを知っている人はいますか?手作業でやるのはちょっと面倒な気がしますが…

私が見つけた: http://blogs.msdn.com/powershell/archive/2007/09/01/new-and-improved-cmdlet-help-editor-tool.aspx

更新されたバージョンはありますか?モジュールを選択できません。バイナリモジュールがあります。

役に立ちましたか？

解決

私は関係なく、モジュールの彼らかどうか一部のコマンドレットと関数についてMAMLを生成しますPowerShellスクリプトを作成しました。生成されたMAMLは、いくつかの手動編集が必要になりますように、それは完璧ではないが、そうあなたは、参照コマンドレットのヘルプエディタがありません。私はそれについてのブログ記事を持っているここを

あなたがそれを使用して見つけた場合は修正が更新気軽に PoshCode の上でスクリプトます。

他のヒント

私は自分のモジュールを文書化しなければならなかったし、私自身のMAMLヘルプビルダーを作成するよりも、任意のより良い解決策を見つけることができませんでした。ここにあります： https://github.com/nightroman/Helpsする

モジュールは、PowerShellのヘルプスクリプトからPowerShellのMAMLのヘルプファイルを作成します。 ヘルプスクリプトは、結果のヘルプと非常に似て、ほとんどWYSIWYGです。 それでも、彼らはただのスクリプトがあり、これは容易な便利な機能の多くを作ります。 そのうちの一つは、いくつかの文化のためのヘルプファイルを構築しています。

ここでコマンドのヘルプデータのテンプレートがある（コマンドレット、関数、スクリプト）とプロバイダーます：

### Command help data

@{
    command = 'Name'
    synopsis = '...'
    description = '...'
    sets = @{
        Set1 = '...'
        #...
    }
    parameters = @{
        Param1 = '...'
        #...
    }
    inputs = @(
        @{
            type = '...'
            description = '...'
        }
        #...
    )
    outputs = @(
        @{
            type = '...'
            description = '...'
        }
        #...
    )
    notes = '...'
    examples = @(
        @{
            title = '...'
            introduction = '...'
            code = {
            }
            remarks = '...'
            test = {
                . $args[0]
            }
        }
        #...
    )
    links = @(
        @{
            text = '...'
            URI = '...'
        }
        #...
    )
}

### Provider help data

@{
    provider = 'Name'
    drives = '...'
    synopsis = '...'
    description = '...'
    capabilities = '...'
    tasks = @(
        @{
            title = '...'
            description = '...'
            examples = @(
                @{
                    title = '...'
                    introduction = '...'
                    code = {
                    }
                    remarks = '...'
                    test = {
                        . $args[0]
                    }
                }
            )
        }
        #...
    )
    parameters = @(
        @{
            name = '...'
            type = '...'
            description = '...'
            cmdlets = '...'
            values = @(
                @{
                    value = '...'
                    description = '...'
                }
                #...
            )
        }
        #...
    )
    notes = '...'
    links = @(
        @{
            text = '...'
            URI = '...'
        }
        #...
    )
}

私はスナップイン/モジュールのC＃コードに埋め込むドキュメントへの道を見てきたし、 PoshBuildする私の最良の選択肢のように見えるし始めています。これは、ドキュメントの要素（例えば、概要および例）の一部を含める方法を提供していませんが、それはまだ良いオプションです。

XML PowerShell ヘルプ (PSMAML) を編集するためのグラフィカル ツールに関しては、以下を使用できます。

オープンソースの出現により、 XmlDoc2CmdletDoc, を文書化できるようになりました。 バイナリ PowerShell コマンドレット (つまり、C# で書かれたもの）他の C# ライブラリと同様に、 スクリプト化された コマンドレット (PowerShell で記述されたコマンドレット):インラインドキュメントコメントを使用します。

並行性を維持する必要はもうありません MAML 手作業でファイルする！ビルドをインストルメント化するだけで、C# プロジェクトを再コンパイルするときにドキュメント ジェネレーターが実行され、両方の モジュール.dll そして モジュール.dll-ヘルプ.xml. 。後者は、コマンドレットを呼び出すときにコマンドレットに関するヘルプを提供するために PowerShell によって直接使用されます。 Get-Help.

そして、XmlDoc2CmdletDoc は、 -strict コマンドレットを包括的に文書化していることを確認するために切り替えてください。スイッチを使用していて何かを見逃した場合、ビルドは当然失敗します。

XmlDoc2CmdletDoc によって自動的に提供されるその他の利点 (このリストの「セクション」とは、XmlDoc2CmdletDoc によって提供されるヘルプのセクションを指します) Get-Help):

  • の各カスタム タイプ 出力 セクションに説明が含まれています。
  • の 構文 このセクションには、列挙型の可能な値が含まれています。
  • の パラメータ このセクションには、列挙型の可能な値が含まれています。
  • エイリアスは自動的に文書化されます。 パラメーター セクション。
  • エイリアスはファーストクラスのパラメータとして扱われるため、エイリアスについてヘルプを求めることができます。
  • オプションで、パラメータに別の説明を使用できます。 入力 セクションと同様に、 パラメータ セクション。
  • Web リンクは、ライブ リンクへの後処理を可能にするために、マークダウン形式で自動的にレンダリングされます。(この機能強化は保留中です。)

私はこのオープンソース ユーティリティがとても気に入ったので、上記の利点のいくつかを提供するために貢献し始めました。そして、私はそれを使用するための包括的なガイドを書きました。 PowerShell バイナリ コマンドレットの文書化, 、Simple-Talk.com で公開されました。

ライセンス： CC-BY-SA と 帰属
所属していません StackOverflow
scroll top