다음을 통해 공유

PlatyPS를 사용하여 XML 기반 도움말 만들기

PowerShell 모듈을 만들 때는 항상 만드는 cmdlet에 대한 자세한 도움말을 포함하는 것이 좋습니다. cmdlet이 컴파일된 코드에서 구현되는 경우 XML 기반 도움말을 사용해야 합니다. 이 XML 형식을 MAML(Microsoft 지원 태그 언어)라고 합니다.

레거시 PowerShell SDK 설명서에서는 모듈로 패키지된 PowerShell cmdlet에 대한 도움말을 만드는 방법에 대해 자세히 설명합니다. 그러나 PowerShell은 XML 기반 도움말을 만들기 위한 도구를 제공하지 않습니다. SDK 설명서에서는 MAML 도움말의 구조를 설명하지만 복잡한 중첩된 MAML 콘텐츠를 직접 만드는 작업을 남겨 줍니다.

여기서 PlatyPS 모듈이 도움이 될 수 있습니다.

PlatyPS란?

PlatyPS는 MAML을 더 쉽게 만들고 유지 관리할 수 있도록 해커톤 프로젝트로 시작된 오픈 소스 도구입니다. PlatyPS는 매개 변수 집합의 구문과 모듈의 각 cmdlet에 대한 개별 매개 변수를 문서화합니다. PlatyPS는 구문 정보를 포함하는 구조적 Markdown 파일을 만듭니다. 설명을 만들거나 예제를 제공할 수 없습니다.

PlatyPS는 설명 및 예제를 채울 자리 표시자를 만듭니다. 필요한 정보를 추가한 후 PlatyPS는 Markdown 파일을 MAML 파일로 컴파일합니다. PowerShell의 도움말 시스템은 일반 텍스트 개념 도움말 파일(항목 정보)도 허용합니다. PlatyPS에는 파일에 대한 새 대한 구조화된 Markdown 템플릿을 만드는 cmdlet이 있지만 이러한 파일을 수동으로 유지 관리해야 합니다.

모듈에 MAML 및 텍스트 도움말 파일을 포함할 수 있습니다. PlatyPS를 사용하여 업데이트 가능한 도움말을 위해 호스팅할 수 있는 CAB 패키지로 도움말 파일을 컴파일할 수도 있습니다.

PlatyPS 사용 시작

먼저 PowerShell 갤러리에서 PlatyPS를 설치해야 합니다.

# Install using PowerShellGet 2.x
Install-Module platyps -Force

# Install using PSResourceGet 1.x
Install-PSResource platyps -Reinstall

PlatyPS를 설치한 후 모듈을 세션으로 가져옵니다.

Import-Module platyps

다음 순서도에서는 PowerShell 참조 콘텐츠를 만들거나 업데이트하는 프로세스를 간략하게 설명합니다.

PlatyPS 사용하여 XML 기반 도움말을 만들기 위한 워크플로

PowerShell 모듈에 대한 Markdown 콘텐츠 만들기

  1. 새 모듈을 세션으로 가져옵니다. 문서화해야 하는 각 모듈에 대해 이 단계를 반복합니다.

    다음 명령을 실행하여 모듈을 가져옵니다.

    Import-Module <your module name>

  2. PlatyPS를 사용하여 모듈 페이지 및 모듈 내의 모든 연결된 cmdlet에 대한 Markdown 파일을 생성합니다. 문서화해야 하는 각 모듈에 대해 이 단계를 반복합니다.

    $OutputFolder = <output path>
$parameters = @{
    Module = <ModuleName>
    OutputFolder = $OutputFolder
    AlphabeticParamsOrder = $true
    WithModulePage = $true
    ExcludeDontShow = $true
    Encoding = [System.Text.Encoding]::UTF8
}
New-MarkdownHelp @parameters

New-MarkdownAboutHelp -OutputFolder $OutputFolder -AboutName "topic_name"

    출력 폴더가 없으면 New-MarkdownHelp 만듭니다. 이 예제에서 New-MarkdownHelp 모듈의 각 cmdlet에 대한 Markdown 파일을 만듭니다. 또한 <ModuleName>.md파일에 모듈 페이지 만듭니다. 이 모듈 페이지에는 모듈에 포함된 cmdlet 목록과 Synopsis 설명의 자리 표시자가 포함되어 있습니다. 모듈 페이지의 메타데이터는 모듈 매니페스트에서 가져온 것이며 PlatyPS에서 HelpInfo XML 파일을 만드는 데 사용됩니다(아래 설명).

    파일에 대한 새 만듭니다.

    자세한 내용은 New-MarkdownHelp 및 New-MarkdownAboutHelp참조하세요.

모듈이 변경되면 기존 Markdown 콘텐츠 업데이트

PlatyPS는 모듈에 대한 기존 Markdown 파일을 업데이트할 수도 있습니다. 이 단계를 사용하여 새 cmdlet, 새 매개 변수 또는 변경된 매개 변수가 있는 기존 모듈을 업데이트합니다.

  1. 새 모듈을 세션으로 가져옵니다. 문서화해야 하는 각 모듈에 대해 이 단계를 반복합니다.

    다음 명령을 실행하여 모듈을 가져옵니다.

    Import-Module <your module name>

  2. PlatyPS를 사용하여 모듈 방문 페이지 및 모듈 내의 모든 연결된 cmdlet에 대한 Markdown 파일을 업데이트합니다. 문서화해야 하는 각 모듈에 대해 이 단계를 반복합니다.

    $parameters = @{
    Path = <folder with Markdown>
    RefreshModulePage = $true
    AlphabeticParamsOrder = $true
    UpdateInputOutput = $true
    ExcludeDontShow = $true
    LogPath = <path to store log file>
    Encoding = [System.Text.Encoding]::UTF8
}
Update-MarkdownHelpModule @parameters

    Update-MarkdownHelpModule 지정된 폴더의 cmdlet 및 모듈 Markdown 파일을 업데이트합니다. about_*.md 파일을 업데이트하지 않습니다. 모듈 파일(ModuleName.md)은 cmdlet 파일에 추가된 새 Synopsis 텍스트를 받습니다. cmdlet 파일에 대한 업데이트에는 다음과 같은 변경 내용이 포함됩니다.

    • 새 매개 변수 집합
    • 새 매개 변수
    • 업데이트된 매개 변수 메타데이터
    • 입력 및 출력 형식 정보 업데이트됨

    자세한 내용은 Update-MarkdownHelpModule참조하세요.

새 파일 또는 업데이트된 Markdown 파일 편집

PlatyPS는 매개 변수 집합의 구문과 개별 매개 변수를 문서화합니다. 설명을 만들거나 예제를 제공할 수 없습니다. 콘텐츠가 필요한 특정 영역은 중괄호에 포함됩니다. 예: {{ Fill in the Description }}

VS Code 자리 표시자를 보여 주는 Markdown 템플릿

개요, cmdlet에 대한 설명, 각 매개 변수에 대한 설명 및 하나 이상의 예제를 추가해야 합니다.

PowerShell 콘텐츠 작성에 대한 자세한 내용은 다음 문서를 참조하세요.

메모

PlatyPS에는 cmdlet 참조에 사용되는 특정 스키마가 있습니다. 이 스키마는 문서의 특정 섹션에서 특정 Markdown 블록만 허용합니다. 콘텐츠를 잘못된 위치에 배치하면 PlatyPS 빌드 단계가 실패합니다. 자세한 내용은 PlatyPS 리포지토리의 스키마 설명서를 참조하세요. 올바른 형식의 cmdlet 참조의 전체 예제는 Get-Item참조하세요.

각 cmdlet에 필요한 콘텐츠를 제공한 후에는 모듈 방문 페이지를 업데이트해야 합니다. 모듈에 <module-name>.md 파일의 YAML 메타데이터에 올바른 Module Guid 및 Download Help Link 값이 있는지 확인합니다. 누락된 메타데이터를 추가합니다.

또한 일부 cmdlet에 Synopsis(간단한 설명)이 누락될 수 있습니다. 다음 명령은 Synopsis 설명 텍스트로 모듈 방문 페이지를 업데이트합니다. 모듈 방문 페이지를 열어 설명을 확인합니다.

Update-MarkdownHelpModule -Path <full path output folder> -RefreshModulePage

이제 모든 콘텐츠를 입력했으므로 PowerShell 콘솔에서 Get-Help 표시되는 MAML 도움말 파일을 만들 수 있습니다.

외부 도움말 파일 만들기

이 단계에서는 PowerShell 콘솔에서 Get-Help 표시되는 MAML 도움말 파일을 만듭니다.

MAML 파일을 빌드하려면 다음 명령을 실행합니다.

New-ExternalHelp -Path <folder with MDs> -OutputPath <output help folder>

New-ExternalHelp 모든 cmdlet Markdown 파일을 하나 이상의 MAML 파일로 변환합니다. 정보 파일은 이름 형식인 about_topic_name.help.txt일반 텍스트 파일로 변환됩니다. Markdown 콘텐츠는 PlatyPS 스키마의 요구 사항을 충족해야 합니다. 콘텐츠가 스키마를 따르지 않으면 New-ExternalHelp 오류와 함께 종료됩니다. 스키마 위반을 해결하려면 파일을 편집해야 합니다.

주의

PlatyPS는 about_*.md 파일을 일반 텍스트로 변환하는 작업을 제대로 수행하지 않습니다. 허용 가능한 결과를 얻으려면 매우 간단한 Markdown을 사용해야 합니다. PlatyPS에서 파일을 변환하도록 허용하는 대신 일반 텍스트 about_topic_name.help.txt 형식으로 파일을 유지할 수 있습니다.

이 단계가 완료되면 대상 출력 폴더에 *-help.xml 및 about_*.help.txt 파일이 표시됩니다.

자세한 내용은 New-ExternalHelp 참조하세요.

컴파일된 도움말 파일 테스트

Get-HelpPreview cmdlet을 사용하여 콘텐츠를 확인할 수 있습니다.

Get-HelpPreview -Path "<ModuleName>-Help.xml"

cmdlet은 컴파일된 MAML 파일을 읽고 Get-Help받는 것과 동일한 형식으로 콘텐츠를 출력합니다. 이렇게 하면 결과를 검사하여 Markdown 파일이 올바르게 컴파일되었는지 확인하고 원하는 결과를 생성할 수 있습니다. 오류가 발견되면 Markdown 파일을 다시 편집하고 MAML을 다시 컴파일합니다.

이제 도움말 파일을 게시할 준비가 되었습니다.

도움말 게시

이제 Markdown 파일을 PowerShell 도움말 파일로 컴파일했으므로 사용자가 파일을 사용할 수 있도록 할 준비가 되었습니다. PowerShell 콘솔에서 도움말을 제공하는 두 가지 옵션이 있습니다.

  • 모듈을 사용하여 도움말 파일 패키지
  • 사용자가 Update-Help cmdlet을 사용하여 설치하는 업데이트 가능한 도움말 패키지 만들기

모듈에 대한 패키징 도움말

도움말 파일은 모듈을 사용하여 패키지할 수 있습니다. 폴더 구조에 대한 자세한 내용은 모듈 대한 도움말 작성을 참조하세요. 모듈 매니페스트의 FileList 키 값에 도움말 파일 목록을 포함해야 합니다.

업데이트 가능한 도움말 패키지 만들기

개략적으로 업데이트 가능한 도움말을 만드는 단계는 다음과 같습니다.

  1. 도움말 파일을 호스트할 인터넷 사이트 찾기
  2. 모듈 매니페스트에 HelpInfoURI 키 추가
  3. HelpInfo XML 파일 만들기
  4. CAB 파일 만들기
  5. 파일 업로드

자세한 내용은 지원 업데이트 가능한 도움말: 단계별참조하세요.

PlatyPS는 이러한 단계 중 일부를 지원합니다.

HelpInfoURI 도움말 파일이 인터넷에서 호스트되는 위치를 가리키는 URL입니다. 이 값은 모듈 매니페스트에서 구성됩니다. Update-Help 모듈 매니페스트를 읽고 이 URL을 가져와 업데이트 가능한 도움말 콘텐츠를 다운로드합니다. 이 URL은 개별 파일이 아닌 폴더 위치만 가리킵니다. Update-Help 모듈 매니페스트 및 HelpInfo XML 파일의 다른 정보를 기반으로 다운로드할 파일 이름을 생성합니다.

중요하다

HelpInfoURI 슬래시 문자(/)로 끝나야 합니다. 해당 문자가 없으면 Update-Help 콘텐츠를 다운로드할 올바른 파일 경로를 생성할 수 없습니다. 또한 대부분의 HTTP 기반 파일 서비스는 대/소문자를 구분합니다. HelpInfo XML 파일의 모듈 메타데이터에 적절한 문자 대/소문자가 포함되어 있는 것이 중요합니다.

New-ExternalHelp cmdlet은 출력 폴더에 HelpInfo XML 파일을 만듭니다. HelpInfo XML 파일은 모듈 Markdown 파일(ModuleName.md)에 포함된 YAML 메타데이터를 사용하여 빌드됩니다.

New-ExternalHelpCab cmdlet은 컴파일한 MAML 및 about_*.help.txt 파일이 포함된 ZIP 및 CAB 파일을 만듭니다. CAB 파일은 모든 버전의 PowerShell과 호환됩니다. PowerShell 6 이상에서는 ZIP 파일을 사용할 수 있습니다.

$helpCabParameters = @{
    CabFilesFolder = $MamlOutputFolder
    LandingPagePath = $LandingPage
    OutputFolder = $CabOutputFolder
}
New-ExternalHelpCab @helpCabParameters

ZIP 및 CAB 파일을 만든 후 HTTP 파일 서버에 ZIP, CAB 및 HelpInfo XML 파일을 업로드합니다. HelpInfoURI표시된 위치에 파일을 배치합니다.

자세한 내용은 new-ExternalHelpCab참조하세요.

기타 게시 옵션

Markdown은 게시를 위해 다른 형식으로 쉽게 변환할 수 있는 다양한 형식입니다. Pandoc같은 도구를 사용하여 Markdown 도움말 파일을 일반 텍스트, HTML, PDF 및 Office 문서 형식을 비롯한 다양한 문서 형식으로 변환할 수 있습니다.

또한 PowerShell 6 이상에서 ConvertFrom-Markdown 및 Show-Markdown cmdlet을 사용하여 Markdown을 HTML로 변환하거나 PowerShell 콘솔에서 다채로운 디스플레이를 만들 수 있습니다.

알려진 문제

PlatyPS는 만들고 컴파일하는 Markdown 파일의 구조에 대한 스키마 매우 중요합니다. 이 스키마를 위반하는 매우 쉬운 쓰기 유효한 Markdown입니다. 자세한 내용은 PowerShell 스타일 가이드 및 편집 참조 문서참조 문서를 참조하세요.