Tworzymy moduł: pomoc się pisze!

pisze-pomocDziś 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:

platyPS-lista-polecen

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ń:

platyPS-tworzy-pomoc

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:

markdown-w-VS-Code

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:

pomoc-PowerShell-z-pliku-xml

Doskonały sposób by zjeść ciasteczko i mieć ciasteczko… Winking smileOczywiś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.

Skomentuj

Wprowadź swoje dane lub kliknij jedną z tych ikon, aby się zalogować:

Logo WordPress.com

Komentujesz korzystając z konta WordPress.com. Wyloguj /  Zmień )

Zdjęcie na Google

Komentujesz korzystając z konta Google. Wyloguj /  Zmień )

Zdjęcie z Twittera

Komentujesz korzystając z konta Twitter. Wyloguj /  Zmień )

Zdjęcie na Facebooku

Komentujesz korzystając z konta Facebook. Wyloguj /  Zmień )

Połączenie z %s

 
%d blogerów lubi to: