Tworzymy moduł: pomoc się pisze!
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:
# Pomoc dla lokalizacji pl-PL (w końcu pisalismy naszą pomoc w tym języku) | |
New-ExternalHelp -OutputPath .\PowerShellPL\pl-PL -Path .\Pomoc\ -Force -ErrorAction Stop | |
# Nie zaszkodzi też tę samą pomoc umiescić w "domyślnym" en-US... pomoc w obcym języku lepsza niż żadna? 😉 | |
New-ExternalHelp -OutputPath .\PowerShellPL\en-US -Path .\Pomoc\ -Force -ErrorAction Stop |
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.