Aktualizacje naszego środowiska dokumentacji programu PowerShell

Autorem tego postu jest Jeff Sandquist, dyrektor naczelny zespołu ds. rozwoju i ekosystemu platformy Azure.

Dzisiaj uruchomiliśmy nasze odnowione środowisko Azure PowerShell dla docs.microsoft.com. Ulepszenia tego środowiska obejmują obsługę wersji modułu, wyróżnianie składni kodu, łatwiejszy w nawigowaniu spis treści, możliwość edytowania i poprawiania dokumentów i wiele więcej. Z opinii klientów wynika, że zawartość programu PowerShell stanowiła obszar do poprawy i to właśnie kolejny etap naszej podróży w drodze do poprawy jakości zawartości. Zaczęliśmy od platformy Azure, ale w najbliższych miesiącach będziemy przenosić całą zawartość programu PowerShell do tego środowiska.

Ujednolicona dokumentacja dotycząca modułów programu PowerShell

Celem dokumentacji modułów programu PowerShell jest udostępnianie ujednoliconego środowiska dla wszystkich modułów programu PowerShell dostarczanych przez firmę Microsoft. Obejmuje on:

• Spójne wzorce adresów URL — jeśli znasz nazwę modułu lub jego polecenia cmdlet, znasz jego adres URL. Wzorzec adresu URL używany w witrynie Docs to: docs.microsoft.com/powershell/module/{nazwa-modułu}/{nazwa-polecenia-cmdlet}/. Dla polecenia Get-AzureRMStorageAccount znajdującego się w module AzureRM.Storage adres URL będzie następujący: https://docs.microsoft.com/powershell/module/azurerm.storage/get-azurermstorageaccount
• Spójne środowisko użytkownika — formatowanie modułów, poleceń cmdlet i przykładów odbywa się teraz w taki sam sposób w całym środowisku dokumentacji programu PowerShell.
• Łatwe współtworzenie — użytkownicy programu PowerShell mogą dodawać przykłady kodu lub edytować naszą dokumentację, klikając przycisk Edytuj bezpośrednio na stronie dokumentu.
• Obsługa wersji dla wcześniejszych wersji programu PowerShell — aby odfiltrować określoną wersję programu Azure PowerShell, wystarczy użyć selektora wersji na stronie.

Obsługa wersji programu PowerShell

Wspominając o obsłudze wersji określonego modułu, należy pamiętać, że niektóre moduły składają się z grupy innych modułów, z których każdy ma własny schemat obsługi wersji. Na przykład klienci pobierają program Azure PowerShell przy użyciu narzędzia PowerShellGet. W przeszłości klienci musieli ręcznie odszyfrowywać wersje dokumentów obowiązujące w przypadku ich instalacji. Jeśli na przykład zainstalowano program Azure PowerShell 3.7, trzeba było znać każdy moduł dostarczany przez usługę AzureRM 3.7 wraz z wersjami AzureRM.Automation 2.7 i AzureRM.CognitiveServices v0.5.0 i wyszukiwać dokumentację.

Dzięki nowemu środowisku wystarczy tylko wybrać jedną wersję, a my odfiltrujemy prawidłowe moduły na podstawie zainstalowanej wersji.

Poprawiony spis treści

Oprócz poleceń cmdlet dodaliśmy przegląd zawartości, kroki instalacji, wprowadzenie i przykłady. W przypadku dokumentacji platformy Azure pogrupowaliśmy także polecenia cmdlet na podstawie usługi platformy Azure.

Łatwe filtrowanie ze spisu treści podczas pisania

Z łatwością można filtrować lewą stronę spisu treści podczas pisania, aby wyszukać pasujące do wpisywanych słów polecenia cmdlet lub usługi.

Ulepszenia strony poleceń cmdlet

Udoskonalone kolorowanie i formatowanie

Polecenia cmdlet programu PowerShell są teraz pokolorowane i sformatowane w sposób zwiększający ich czytelność.

Ulepszenia parametrów

Wcześniej parametry były grupowane na podstawie tego, czy są wymagane, czy opcjonalne, ale lista parametrów była wyświetlana jako nieuporządkowana. Zamiast tego dodaliśmy nagłówki sekcji w celu grupowania parametrów wymaganych i parametrów opcjonalnych oraz poprawiliśmy kolorowanie/styl nazw parametrów.

Inteligentniejsze zachowanie funkcji kopiowania/wklejania

Wiele naszych przykładów kodu poleceń cmdlet programu PowerShell ma prefiks tekstowy PS C:\>. Teraz kliknięcie przycisku Kopiuj w przykładzie kodu będzie powodować pominięcie prefiksu PS C:\>, jak pokazano na poniższym zrzucie ekranu Notatnika.

Twoja opinia

Mamy nadzieję, że w tej wersji dostrzegasz znaczne ulepszenia.