Microsoft.PowerShell.PlatyPS kullanarak yeni komut yardımı Markdown oluşturma

Microsoft.PowerShell.PlatyPS (PlatyPS) modülü, MAML yardım dosyalarını el ile yazmak yerine, Markdown biçiminde komut belgeleri oluşturmanıza ve ardından Markdown dosyalarını MAML biçimine dönüştürmenize olanak tanır. PlatyPS, modülünüzdeki her komut için bir Markdown şablonu oluşturur. PlatyPS yardım içeriğini sizin için yazmaz. Şablonu komutları, parametreleri, örnekleri ve diğer destekleyici bilgileri açıklayan içerikle doldurmanız gerekir.

MAML yardım içeriği oluşturma aşağıdaki adımlardan oluşur:

  1. Modülünüz için Markdown şablon dosyalarını oluşturun.
  2. İçerik eklemek için Markdown dosyalarını düzenleyin.
  3. Yapının doğru olduğundan emin olmak için Markdown dosyalarını test edin.
  4. Markdown dosyalarını MAML biçimine dönüştürün ve yardım yayımlayın

Bu makalede ilk üç adım açıklanmaktadır.

Önkoşullar

Başlamadan önce PowerShell Galerisi Microsoft.PowerShell.PlatyPS modülünü yüklemeniz gerekir. Belgelemek istediğiniz modülü de yüklemiş olmanız gerekir.

PlatyPS'yi yüklemek için aşağıdaki komutu kullanın:

Install-PSResource -Name Microsoft.PowerShell.PlatyPS

1. Adım - Markdown şablon dosyalarını oluşturma

Modülünüz için oluşturulacak iki tür Markdown dosyası vardır:

  • Komut yardım dosyaları - her komut için bir dosya.
  • Modül dosyası - modülle ilgili meta verileri içerir ve modüldeki komutları listeler.

Modülünüz için MAML içeriği oluşturmak istiyorsanız her iki dosya türü de gereklidir.

Markdown dosyalarını oluşturmak için aşağıdaki komutu çalıştırın:

$newMarkdownCommandHelpSplat = @{
    ModuleInfo = Get-Module -Name 'YourModuleName'
    OutputFolder = './docs'
    WithModulePage = $true
}
New-MarkdownCommandHelp @newMarkdownCommandHelpSplat

Komut, New-MarkdownCommandHelp geçerli dizinde adlandırılmış ./docs/YourModuleName bir klasör oluşturur. Klasör, modüldeki her komut için Markdown dosyalarının yanı sıra adlı YourModuleName.mdbir modül dosyasını içerir. Modül dosyası, modülle ilgili meta verileri içerir ve her komutu özet açıklamasıyla birlikte listeler. Bu dosya, bir dokümantasyon web sitesinde modül için dizin sayfası olarak kullanılmak üzere HTML'ye dönüştürülebilir.

Modül dosyası ilk oluşturulduğunda, komutlar için özet açıklamaları yoktur. Markdown dosyaları, özet açıklamalarıyla değiştirmeniz gereken yer tutucular içerir.

WithModulePage parametresini atlarsanız, modül dosyası oluşturulmaz. Modül dosyasını daha sonra özet açıklamalarını yazdıktan sonra komutunu çalıştırarak New-MarkdownModuleFile oluşturabilirsiniz. Örneğin:

Measure-PlatyPSMarkdown -Path ./docs/YourModuleName/*.md |
    Where-Object Filetype -match 'CommandHelp' |
    Import-MarkdownCommandHelp -Path {$_.FilePath} |
    New-MarkdownModuleFile -OutputFolder ./docs -Force

Bu komut, klasördeki ./docs/YourModuleName modül dosyasını oluşturur. Parametre -Force , var olan herhangi bir modül dosyasının üzerine yazar. Komut dosyalarındaki özet açıklamalarını doldurduysanız, açıklamalar modül dosyasına dahil edilir.

Bu komutlar hakkında daha fazla bilgi için aşağıdaki makalelere bakın:

Sonraki Adımlar

  • Last updated on