none
Документирование PowerShell RRS feed

  • Общие обсуждения

  • Продолжаем попытки документировать PowerShell. Читать помощь с экрана командной строки - это, конечно, хорошо. Но очень неудобно. Можно сгенерировать все разделы помощи в текстовые файлы, но при этом трудно перемещаться между ними.

     Появилась идея сгенерировать файлы помощи в HTML файлы и связать их гиперссылками. Пока удалось сделать следующее:

    • Все разделы помощи PowerShell сгруппированы в
      • Aliase - Описание псевдонимов.
      • Cmdlet - Описание Командлет.
      • HelpFile - Общие разделы помощи.
      • Provider - Описание провайдеров информационных структур. 

    За исключением “HelpFile”, остальные разделы помощи хорошо структурированы, поэтому из них удалось сгенерировать HTML файлы. Разделы HelpFile представляют собой обычный текст и выделить из них подразделы пока не получилось, а наличие в некоторых из них таблиц затруднило генерацию HTML. Поэтому разделы помощи из HelpFile пока оставлены в виде текста.

     

    Далее собственно скрипт.

     

    Code Snippet

    #############################################
    # Функции удаления и замены символов, перед
    # генерацией HTML.
    #############################################

     

    function LTGT
    {
    Param ([string]$InStr)
    ($InStr -replace "<", "&lt;") -replace ">","&gt;"
    }

     

    function CRLF
    {
    Param ([string]$InStr)
    ($InStr -replace "`n","<BR>`n") -replace "     ","<span style='mso-tab-count:1'>     </span>"
    ((($InStr -replace "`n","<BR>`n") -replace "`r","") -replace "`t","    ") -replace "     ","<span style='mso-tab-count:1'>     </span>"
    }

     

    ########################################################################################
    # Собственно функция генерации HTML файла.
    #
    # Входные параметры:
    # XRootPath   - Путь к корневому каталогу, в котором будут сохранены файлы разделов Помощи
    # XHelpItem   - Наименование текущего раздела Помощи
    # XHelpCategory  - Наименование категории текущего раздела Помощи
    ########################################################################################
    function WriteHelpToHTML
    {
    Param ([string]$XRootPath, [string]$XHelpItem, [string]$XHelpCategory)

    $X = Get-Help $XHelpItem -full

     

    # Заголовок
    $HtmlHeader = "<!DOCTYPE HTML PUBLIC `"-//W3C//DTD HTML 4.01//EN`" `"http://www.w3.org/TR/html4/strict.dtd`"> <html><head> <title>" + $X.name + "</title> </head>`n`n"

     

    # Имя
    $XName = "<P><H4>ИМЯ</H4></P>`n"
    $XName = $XName + "<P>" + (LTGT $X.name) + "</P>`n"

     

    # Описание
    $XSynopsis = "<P><H4>ОПИСАНИЕ</H4></P>`n"
    $XSynopsis = $XSynopsis + "<P>" + (LTGT $X.synopsis) + "</P>`n"

     

    # Синтаксис
    $XSyntax = "<P><H4>СИНТАКСИС</H4></P>`n"
    foreach($Item1 in $X.syntax.syntaxItem)
    {
     $XSyntax = $XSyntax + "<P><Code><B>" + (LTGT $Item1.name) + "</B>"
     foreach($Item2 in $Item1.parameter)
     {
      if ($Item2.parameterValue.length -gt 0){$XParamType = "&lt;"+$Item2.parameterValue+"&gt;"}
      else {$XParamType = ""}
      $XSyntax = $XSyntax + " [-" + (LTGT $Item2.name) + " " + (LTGT $XParamType) + "]"
     }
     $XSyntax = $XSyntax + "</Code></P>`n"
    }

     

    # Подробное описание
    $XDesc = "<P><H4>ПОДРОБНОЕ ОПИСАНИЕ</H4></P>`n"
    foreach($Item in $X.description){$XDesc = $XDesc + "<P><Code><I>" + (LTGT $Item.text) + "</I></Code></P>`n"}

     

    # Параметры
    $XParam = "<P><H4>ПАРАМЕТРЫ</H4></P>`n"
    foreach ($Item1 in $X.parameters.parameter)
    {
     $XParam = $XParam + "<P><Code>-<B>" + (LTGT $Item1.name) + "</B> &lt;<I>" + $Item1.ParameterValue + "</I>&gt;<BR>`n"
     foreach ($Item2 in $Item1.description)
     {
      $XParam = $XParam + "<I>" + (LTGT $Item2.text) + "</I><BR><BR>`n`n"
     }
     $XParam = $XParam + "Требуется ? - <B>" + (LTGT $Item1.required) + "</B><BR>`n"
     $XParam = $XParam + "Позиция ? - <B>" + (LTGT $Item1.position) + "</B><BR>`n"
     $XParam = $XParam + "Значение по умолчанию: - <B>" + (LTGT $Item1.DefaultValue) + "</B><BR>`n"
     $XParam = $XParam + "Принимать входные данные из конвейера ? - <B>" + (LTGT $Item1.pipelineInput) + "</B><BR>`n"
     $XParam = $XParam + "Принимать подстановочные знаки ? - <B>" + (LTGT $Item1.globbing) + "</B><BR>`n"
     
     $XParam = $XParam + "</Code></P>`n"
    }

     

    # Тип ввода
    $XInputType = "<P><H4>ТИП ВВОДА</H4></P>`n"
    $XInputType = $XInputType + "<P><Code><B>" + (LTGT $X.inputTypes.InputType.type.name) +"</B></Code></P>`n"
    foreach($Item1 in $X.inputTypes.InputType.type.description)
    {
     $XInputType = $XInputType + "<P><Code><I>" + (LTGT $Item1.text) +"</I></Code></P>`n"
    }
    if ($X.inputTypes.InputType.description.length -gt 0)
    {
     $XInputType = $XInputType + "<P><Code><I>" + (LTGT $X.inputTypes.InputType.description) +"</I></Code></P>`n"
    }

     

    # Примечания
    $XAlertSet = "<P><H4>ПРИМЕЧАНИЯ</H4></P>`n"
    if ($X.alertSet.title.length -gt 0)
    {
     $XAlertSet = $XAlertSet + "<P><B>" + (LTGT $X.alertSet.title) +"</B></P>`n"
    }
    foreach($Item1 in $X.alertSet.alert)
    {
     if ($Item1.text.length -gt 0)
     {
      $XAlertSet = $XAlertSet + "<P><Code><I>" + (LTGT $Item1.text) +"</I></Code></P>`n"
     }
    }

     

    # Примеры
    $XExamples = "<P><H4>ПРИМЕРЫ</H4></P>`n"
    foreach($Item1 in $X.examples.example)
    {
     $XExamples = $XExamples + "<P>" + $Item1.title + "<BR><Code>`n"
     foreach ($Item2 in $Item1.introduction)
     {
      $XExamples = $XExamples + (LTGT $Item2.text) + (LTGT $Item1.code) + "<BR>`n"
     }
     $XExamples = $XExamples + "</Code></P>`n"
     
     foreach ($Item2 in $Item1.remarks)
     {
      if ($Item2.text.length -gt 0)
      {
       $XExamples = $XExamples + "<P><Code><I>" + (LTGT $Item2.text) + "</I></Code></P>`n"
      }
     }
    }

     

    # Ссылки по теме
    $XLinks = "<P><H4>ССЫЛКИ ПО ТЕМЕ</H4></P>`n"
    foreach ($Item1 in $X.relatedLinks.navigationLink)
    {
     $LinkName = $Item1.linkText
      
     # Выделяем категории ссылок ассоциативно, так как непонятно как определять существование ссылок в БД ...
     if ($LinkName -like "about*")
     {
      $LinkCategory = "HelpFile"
      $Ext = ".txt"
     }
     else {
      $LinkCategory = "CmdLet"
      $Ext = ".htm"
     }
     
     $LinkPath = "..\" + $LinkCategory + "\" + $LinkName + $Ext
     $XLinks = $XLinks + "<P><A href='" + $LinkPath + "'>" + $LinkName + "</A></P>`n"
    }

     

    # Диски
    $XDisks = "<P><H4>ДИСКИ</H4></P>`n"
    foreach ($Item1 in $X.Drives)
    {
     $XDisks = $XDisks + "<P>" + (LTGT $Item1.text) + "</P>`n"
    }

     

    # Подробное описание
    $XDetailedDesc = "<P><H4>ПОДРОБНОЕ ОПИСАНИЕ</H4></P>`n"
    foreach ($Item1 in $X.DetailedDescription)
    {
     $XDetailedDesc = $XDetailedDesc + "<P><Code><I>" + (LTGT $Item1.text) + "</I></Code></P>`n"
    }

     

    # Возможности
    $XCapabilities = "<P><H4>ВОЗМОЖНОСТИ</H4></P>`n"
    foreach ($Item1 in $X.Capabilities)
    {
     $XCapabilities = $XCapabilities + "<P>" + (LTGT $Item1.text) + "</P>`n"
    }

     

    #Задачи
    $XTasks = "<P><B>ЗАДАЧИ</B></P>`n"
    foreach ($Item1 in $X.Tasks.Task)
    {
     $XTasks = $XTasks + "<P>" + (LTGT $Item1.title) + "</P>`n"
     
     foreach ($Item2 in $Item1.Examples.Example)
     {
      $XTasks = $XTasks + "<P>" + (LTGT $Item2.title) + "</P>`n"
      foreach ($Item3 in $Item2.introduction)
      {
       $XTasks = $XTasks + "<P>" + (LTGT $Item3.text) + "</P>`n"
      }
      $XTasks = $XTasks + "<P><Code>" + (LTGT $Item2.code) + "</Code></P>`n"
      foreach ($Item3 in $Item2.remarks)
      {
       $XTasks = $XTasks + "<P><Code><I>" + (LTGT $Item3.text) + "</I></Code></P>`n"
      }
     }
     foreach ($Item2 in $Item1.Examples.Description)
     {
      $XTasks = $XTasks + "<P><Code><I>" + (LTGT $Item2.text) + "</I></Code></P>`n"
     }
    }

     

    # Динамические параметры
    $XDynamicParam = "<P><H4>ДИНАМИЧЕСКИЕ ПАРАМЕТРЫ</H4></P>`n"
    $DP = $X.DynamicParameters.DynamicParameter
    $XDynamicParam = $XDynamicParam + "<P><Code>-<B>" + (LTGT $DP.name) + "</B> &lt;" + (LTGT $DP.type.name) + "&gt;</Code></P>`n"
    $XDynamicParam = $XDynamicParam + "<P><I>" + (LTGT $DP.desription) + "</I></P>`n"
    $XDynamicParam = $XDynamicParam + "<P>Поддерживаемые командлеты: " + (LTGT $DP.cmdletsupported) + "</P>`n"

    foreach ($Item1 in $DP.PossibleValues.PossibleValue)
    {
     $XDynamicParam = $XDynamicParam + "<P><Code><B>" + (LTGT $Item1.Value) + "</B></Code><BR>`n"
     foreach ($Item2 in $Item1.description)
     {
      $XDynamicParam = $XDynamicParam + "<Code><I>" + (LTGT $Item2.text) + "</I></Code><BR>`n"
     }
     $XDynamicParam = $XDynamicParam + "</P>`n"
    }

     

    # Примечания
    $XNotes = "<P><B>ПРИМЕЧАНИЯ</B></P>`n"
    $XNotes = $XNotes + "<P>" + (LTGT $X.Notes) + "</P>`n"

    $AllHtml = $HTMLHeader
    $AllHtml = $AllHtml + "<body>`n"
    if ($X.category -eq "HelpFile")
    {
    $AllHtml = $AllHtml + (CRLF (LTGT $X))
    #$AllHtml = $AllHtml + (LTGT $X)
    }
    elseif ($X.category -eq "Provider")
    {
     $AllHtml = $AllHtml + $Xname + $XDisks + $XSynopsis + $XDetailedDesc + $XCapabilities + $XTasks + $XDynamicParam + $XNotes + $XLinks
    }
    else
    {
    $AllHtml = $AllHtml + $Xname + $XSynopsis +$XSyntax + $XDesc + $XParam + $XInputType + $XAlertSet
    $AllHtml = $AllHtml + $XExamples + $XLinks
    $AllHtml = $AllHtml + "</body>`n"
    }

    if ($X.category -eq "HelpFile")
    {
     $AllPath = $XRootPath + "\" + $XHelpCategory + "\" + $XHelpItem + ".txt"
     Write-Output $X >$AllPath
    }
    else
    {
     $AllPath = $XRootPath + "\" + $XHelpCategory + "\" + $XHelpItem + ".htm"
     Write-Output $AllHtml >$AllPath
    }

    Write-Host $AllPath

     

    # Окончание функции WriteHelpToHtml
    }

     

    #######################################################
    # Основное тело скрипта
    #######################################################

    # Получаем значение пути текущего расположения скрипта
    $CurrentPath = Get-Location
    Write-Host $CurrentPath

     

    # Перебираем все категории файлов помощи и формируем для них соответствующие каталоги,
    # если они еще не существуют
    foreach ($HelpTopicCat in get-help * | group category)
    {
     $CategoryName = $HelpTopicCat.Name
     if (test-path $CurrentPath\$CategoryName){}
     else
     {
      md $CurrentPath\$CategoryName
     }
     
     #Write-Host "$CategoryName"
    }

     

    # Перебираем файлы помощи и раскладываем их по соответствующим каталогам
    foreach ($HelpTopicCat in get-help *)
    {
     # Формируем имя целевого файла
     $Name = $HelpTopicCat.Name
     $Category = $HelpTopicCat.Category

     

     WriteHelpToHTML $CurrentPath.path $Name $Category

    }

     

     

    18 февраля 2008 г. 17:49

Все ответы