Обновление документации PowerShell

Автор записи — Джефф Сэндквист (Jeff Sandquist), директор подразделения группы по развитию и экосистеме Azure.

Сегодня мы запустили обновленную систему документации по Azure PowerShell на сайте docs.microsoft.com. Ее усовершенствования включают управление версиями модулей, выделение синтаксиса кода, более удобное оглавление, возможность вносить в документацию правки и многое другое. Мы знаем из отзывов пользователей, что материалы по PowerShell нужно усовершенствовать, что мы и планируем сделать. Мы начинали с документации по Azure, а в ближайшие месяцы перенесем все материалы по PowerShell на эту платформу.

Единый справочник по модулям PowerShell

Задача создания справочной документации по модулям PowerShell — обеспечить согласованный справочный интерфейс для всех модулей PowerShell, предоставляемых корпорацией Майкрософт. В том числе:

• Согласованные шаблоны URL-адресов. Если вы знаете название модуля или командлета, вам должен быть известен и URL-адрес. Шаблон URL-адреса для документации: docs.microsoft.com/powershell/module/{название_модуля}/{название_командлета}/. Для командлета Get-AzureRMStorageAccount, который находится в модуле AzureRM.Storage, URL-адрес будет таким: https://docs.microsoft.com/powershell/module/azurerm.storage/get-azurermstorageaccount
• Согласованный пользовательский интерфейс. Возможности форматирования для модулей, командлетов и примеров теперь являются согласованными для всей документации по PowerShell.
• Удобные функции для добавления материалов. Пользователи PowerShell могут добавлять примеры кода или вносить изменения в наши справочные материалы, нажав кнопку "Изменить" на странице документа.
• Поддержка управления версиями для предыдущих версий PowerShell. Чтобы найти определенную версию Azure PowerShell, используйте средство выбора версий на странице.

Управление версиями PowerShell

Хотя мы упоминали функцию управления версиями для конкретного модуля, не стоит забывать, что некоторые модули предоставляются как группа модулей, каждый из которых имеет собственную схему версий. Например, клиенты скачивают Azure PowerShell через PowerShellGet. Раньше клиентам приходилось самим определять, какие версии документов применяются для установки определенных версий. Например, если вы установили Azure PowerShell 3.7, вам нужно было узнать версию каждого поставляемого с ним отдельного модуля (AzureRM 3.7 поставляется с AzureRM.Automation 2.7 и AzureRM.CognitiveServices версии 0.5.0) и найти соответствующую документацию.

Теперь в нашем новой интерфейсе вам достаточно выбрать только одну версию, установленную на вашем компьютере, а мы отфильтруем и покажем модули, которые ей соответствуют.

Улучшенное оглавление

В дополнение к справочнику по командлетам мы добавили материалы с общими сведениями, инструкции по установке, руководства по началу работы и примеры. В справочнике по Azure командлеты также сгруппированы по службам Azure.

Простая фильтрация содержания при вводе

Вы можете легко фильтровать оглавление в левой части окна. Начните вводить командлеты или названия служб, чтобы отобразилось соответствующее содержимое.

Усовершенствования на странице командлетов

Улучшенная раскраска и форматирование

Командлеты PowerShell теперь красиво выделены цветом и отформатированы для лучшего восприятия.

Улучшения параметров

Хотя раньше параметры были сгруппированы на обязательные и необязательные, список параметров выглядел неупорядоченным. Теперь мы добавили заголовки разделов для группировки обязательных и необязательных параметров и улучшили выделение цветом и с применением стилей для имен параметров.

Умное копирование и вставка

Некоторые примеры кода PowerShell начинаются с текста PS C:\>. Теперь при нажатии кнопки "Копировать" в примере префикс PS C:\> не копируется, как показано на следующем снимке экрана с Блокнотом.

Ваш отзыв

Мы надеемся, что вы заметите значительные улучшения в этом выпуске.