PowerShell po polsku

Dziś przyjrzymy się modułowi, dzięki któremu tworząc pomoc możemy skorzystać z tego samego języka, przy pomocy którego tworzone są strony dokumentacji – markdown. Co prawda pisząc pomoc do naszych modułów w PowerShellu możemy korzystać z pomocy zawartej w komentarzu, dzięki czemu pisanie pomocy jest dość proste, to jednak ciężko wykorzystać tę samą pomoc w innych miejscach (takich jak strony pomocy). Pliki markdown świetnie sprawdzają się w takim scenariuszu. Wykorzystamy do tego moduł platyPS.

Moduł, z którego będziemy korzystali, należy oczywiście w pierwszej kolejności zainstalować. Najlepiej skorzystać w tym celu z galerii modułów. Po instalacji możemy przyjrzeć się dostępnym w ramach tego modułu poleceniom:

Nas najbardziej interesować będą na tym etapie dwa polecenia:

• New-MarkDownHelp – pozwoli nam wygenerować pliki .md dla poleceń w naszym module
• New-ExternalHelp – pozwoli przekształcić pliki .md na plik w formacie XML, zrozumiałe dla systemu pomocy

Aby skorzystać z pierwszego musimy w pierwszej kolejności zaimportować tworzony przez nas moduł. Następnie generujemy pliki .md dla naszych poleceń:

Jeśli nasze funkcje zawierały już pomoc w formacie komentarzy, to zostanie ona automatycznie przeniesiona do tworzonego pliku. Jeśli nie – polecenie utworzy pomoc „szkieletową” z poszczególnymi sekcjami gotowymi do wypełnienia. Jeśli nasz edytor wspiera podgląd plików w formacie markdown, to możemy na bieżąco przyglądać się temu, jak nasza dokumentacja może wyglądać po zakończeniu pracy:

Ważne, by nie usuwać nagłówków i innych elementów języka markdown. Są one niezbędne, by wygenerowana w oparciu o nie pomoc była prawidłowa. Po zakończonej pracy generujemy wspomnianą wyżej pomoc i dodajemy ja do naszego modułu przed jego udostępnieniem:

Tak wygenerowaną pomoc możemy od razu podejrzeć (służy do tego polecenie Get-HelpPreview).

Oczywiście, w przyszłości może się zdarzyć, że nasze polecenie zostanie wzbogacone o nowe parametry, czy inne istotne elementy. Co wtedy? Skorzystać możemy z innego polecenia: Update-MarkDownHelp. Możemy też zaktualizować pomoc dla całego modułu (jeśli dodaliśmy nowe polecenia) – w takiej sytuacji możemy skorzystać z Update-MarkDownHelpModule.

Na koniec nie pozostaje nam nic innego jak tylko spróbować upublicznić naszą pomoc. Jeśli korzystamy z platformy GitHub, to skorzystać możemy z narzędzi GitHub Pages. Przykładowa pomoc dla nieco zaniedbywanego przeze mnie ostatnio modułu EWS utworzona właśnie w ten sposób. Jest to możliwe głównie dzięki temu, że pomoc przechowuje w łatwych w konwersji plikach markdown. Sama pomoc w zainstalowanym module również działa bez zarzutu:

Doskonały sposób by zjeść ciasteczko i mieć ciasteczko… Oczywiście, samo generowanie pomocy najlepiej wykonywać automatycznie. Wrócimy do tego z pewnością w jednym z przyszłych postów.

~ - autor: Bartek Bielawski w dniu 28 października, 2020.

Napisane w PowerShell
Tagi: moduł platyPS, tworzenie pomocy w PowerShellu, tworzymy moduł