Поделиться через

Руководство по стилю для документации PowerShell

В этой статье содержатся рекомендации по стилю, относящиеся к содержимому PowerShell-Docs. Он основывается на сведениях, описанных в обзоре.

Форматирование элементов синтаксиса команд

Используйте следующие правила для форматирования элементов языка PowerShell при использовании элементов в предложении.

  • Всегда используйте полное имя для командлетов и параметров, используя стиль Pascal.

  • Используйте псевдоним только при демонстрации псевдонима.

  • Ключевые слова и операторы PowerShell должны быть строчными.

  • Следующие элементы должны быть отформатированы с помощью полужирного текста:

    • Имена типов

    • Имена классов

    • Имена свойств

    • Имена параметров

      • По умолчанию используйте параметр без префикса дефиса.
      • Используйте имя параметра с дефисом, если вы иллюстрируете синтаксис. Обрамите параметр в обратные кавычки.

      Рассмотрим пример.

      The parameter's name is **Name**, but it's typed as `-Name` when used on the command
line as a parameter.

  • Следующие элементы должны быть отформатированы с помощью обратных апострофов (`):

    • Значения свойств и параметров

    • Имена типов, использующие стиль с скобками, например: [System.Io.FileInfo]

    • Обращение к персонажам по имени. Например, используйте звездочку (*) для подстановочного знака.

    • Ключевые слова и операторы языка

    • Имена командлетов, функций и скриптов

    • Псевдонимы команд и параметров

    • Имена методов— например: ToString() метод возвращает строковое представление объекта.

    • Переменные

    • Собственные команды

    • Пути к файлам и каталогам

    • Примеры синтаксиса встроенных команд— см. раздел Markdown для примеров кода

      В этом примере показаны некоторые примеры backtick:

      The following code uses `Get-ChildItem` to list the contents of `C:\Windows` and assigns
the output to the `$files` variable.

```powershell
$files = Get-ChildItem C:\Windows
```

      В этом примере показан встроенный синтаксис команды:

      To start the spooler service on a remote computer named DC01, you type:
`sc.exe \\DC01 start spooler`.

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

Markdown для примеров кода

Markdown поддерживает два разных стиля кода:

  • Диапазоны кода (встроенные) — помечены одним символом обратной косой черты (`). Используется в абзаце, а не в качестве автономного блока.
  • Блоки кода — многострочный блок, окруженный строками с тройными обратными кавычками (```). Блоки кода также могут иметь метку языка после обратных кавычек. Метка языка включает выделение синтаксиса для содержимого блока кода.

Все блоки кода должны содержаться в заборе кода. Никогда не используйте отступ для блоков кода. Markdown допускает этот шаблон, но он может быть проблематичным и его следует избегать.

Блок кода является одной или несколькими строками кода, окруженными забором кода с тройным обратным (```) забором кода. Маркеры ограждения кода должны находиться в собственной строке до и после примера кода. Открывающий маркер может иметь необязательную метку языка. Метка языка включает выделение синтаксиса на отрисованной веб-странице.

Полный список поддерживаемых тегов языка см. в разделе Блоки кода в централизованном руководстве для участников.

Публикация также добавляет кнопку "Копировать ", которая может скопировать содержимое блока кода в буфер обмена. Это позволяет вставить код в скрипт для тестирования примера кода. Однако не все примеры предназначены для запуска как написанного. Некоторые блоки кода являются основными иллюстрациями концепций PowerShell.

В нашей документации используются три типа блоков кода:

  1. Блоки синтаксиса
  2. Примеры иллюстрации
  3. Примеры исполняемого кода

Блоки кода синтаксиса

Блоки кода синтаксиса используются для описания синтаксической структуры команды. Не используйте тег языка в заборе кода. В этом примере показаны все возможные параметры командлета Get-Command.

```
Get-Command [-Verb <String[]>] [-Noun <String[]>] [-Module <String[]>]
  [-FullyQualifiedModule <ModuleSpecification[]>] [-TotalCount <Int32>] [-Syntax]
  [-ShowCommandInfo] [[-ArgumentList] <Object[]>] [-All] [-ListImported]
  [-ParameterName <String[]>] [-ParameterType <PSTypeName[]>] [<CommonParameters>]
```

В этом примере описывается for инструкция в обобщенных терминах:

```
for (<init>; <condition>; <repeat>)
{<statement list>}
```

Примеры иллюстрации

Иллюстрирующие примеры используются для объяснения концепции PowerShell. Вам следует избегать использования запросов PowerShell в примерах когда это возможно. Однако иллюстрирующие примеры не предназначены для копирования и вставки для выполнения. Они чаще всего используются для простых примеров, которые легко понять. Вы можете включить запрос PowerShell и пример выходных данных.

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

```powershell
PS> 2 -eq 2
True

PS> 2 -eq 3
False

PS> 1,2,3 -eq 2
2

PS> "abc" -eq "abc"
True

PS> "abc" -eq "abc", "def"
False

PS> "abc", "def" -eq "abc"
abc
```

Примеры исполняемого кода

Сложные примеры или примеры, которые должны быть скопированы и выполнены, должны использовать следующую разметку в стиле блоков:

```powershell
<Your PowerShell code goes here>
```

Выходные данные, отображаемые командами PowerShell, должны быть заключены в блок кода вывода , чтобы предотвратить выделение синтаксиса. Рассмотрим пример.

```powershell
Get-Command -Module Microsoft.PowerShell.Security
```

```Output
CommandType  Name                        Version    Source
-----------  ----                        -------    ------
Cmdlet       ConvertFrom-SecureString    3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       ConvertTo-SecureString      3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-Acl                     3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-AuthenticodeSignature   3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-CmsMessage              3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-Credential              3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-ExecutionPolicy         3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-PfxCertificate          3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       New-FileCatalog             3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Protect-CmsMessage          3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-Acl                     3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-AuthenticodeSignature   3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-ExecutionPolicy         3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Test-FileCatalog            3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Unprotect-CmsMessage        3.0.0.0    Microsoft.PowerShell.Security
```

Метка Output кода не является официальным языком , поддерживаемым системой выделения синтаксиса. Однако эта метка полезна, так как наша система публикации добавляет метку вывода в рамку поля кода на веб-странице. Поле "Выходной код" не имеет выделения синтаксиса.

Правила стиля программирования

Избегайте продолжения строки в примерах кода

Избегайте использования символов продолжения строки (`) в примерах кода PowerShell. Символы backtick трудно видеть и могут вызвать проблемы, если в конце строки есть дополнительные пробелы.

  • Используйте PowerShell splatting, чтобы уменьшить длину строки для командлетов с несколькими параметрами.
  • Воспользуйтесь преимуществами возможностей для естественного разрыва строк в PowerShell, таких как после символов пайпа (|), открывающих фигурных скобок ({), круглых скобок (() и квадратных скобок ([).

Избегайте использования запросов PowerShell в примерах

Использование строки запроса не рекомендуется и должно быть ограничено сценариями, которые предназначены для иллюстрации использования командной строки. В большинстве этих примеров строка запроса должна быть PS>. Этот запрос не зависит от индикаторов, относящихся к ОС.

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

PS C:\> cd HKCU:\System\
PS HKCU:\System\> dir

    Hive: HKEY_CURRENT_USER\System

Name                   Property
----                   --------
CurrentControlSet
GameConfigStore        GameDVR_Enabled                       : 1
                       GameDVR_FSEBehaviorMode               : 2
                       Win32_AutoGameModeDefaultProfile      : {2, 0, 1, 0...}
                       Win32_GameModeRelatedProcesses        : {1, 0, 1, 0...}
                       GameDVR_HonorUserFSEBehaviorMode      : 0
                       GameDVR_DXGIHonorFSEWindowsCompatible : 0

Не используйте псевдонимы в примерах

Используйте полные имена всех командлетов и параметров, за исключением случаев, когда вы документируете псевдоним. Имена командлетов и параметров должны использовать правильные имена с регистром Pascal .

Использование параметров в примерах

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

Справочные статьи по командлету форматирования

Справочные статьи командлетов имеют определенную структуру. PlatyPS определяет эту структуру. PlatyPS создает справку командлета для модулей PowerShell в формате Markdown. После изменения файлов Markdown PlatyPS может создать файлы справки MAML, используемые командлетом Get-Help .

PlatyPS имеет схему, которая ожидает определенную структуру для ссылки на командлет. В документе схемы PlatyPS описывается эта структура. Нарушения схемы вызывают ошибки сборки, которые необходимо исправить, прежде чем принять ваш вклад.

  • Не удаляйте ни одну из структур заголовков ATX. PlatyPS ожидает определенный набор заголовков в определенном порядке.
  • Заголовки H2 INPUTS и OUTPUTS должны иметь тип H3. Если командлет не принимает входные данные или не возвращает значение, используйте значение None для H3.
  • Встроенные диапазоны кода можно использовать в любом абзаце.
  • Огражденные блоки кода разрешены только в разделе EXAMPLES.

В схеме PlatyPS EXAMPLES — это заголовок H2. Каждый пример — это заголовок H3. В примере схема не позволяет разделять блоки кода абзацами. Схема допускает только следующую структуру:

### Example X - Title sentence

0 or more paragraphs
1 or more code blocks
0 or more paragraphs.

Номер каждого примера и добавление краткого заголовка.

Рассмотрим пример.

### Example 1: Get cmdlets, functions, and aliases

This command gets the PowerShell cmdlets, functions, and aliases that are installed on the
computer.

```powershell
Get-Command
```

### Example 2: Get commands in the current session

```powershell
Get-Command -ListImported
```

Форматирование About_ файлов

About_* файлы записываются в Markdown, но отправляются как обычные текстовые файлы. Мы используем Pandoc для преобразования Markdown в обычный текст. About_* Файлы форматируются для обеспечения оптимальной совместимости во всех версиях PowerShell и с инструментами публикации.

Основные рекомендации по форматированию:

  • Ограничение строк абзаца до 80 символов

  • Ограничение блоков кода до 76 символов

  • Ограничьте блоки цитат и оповещения до 78 символов

  • При использовании этих специальных мета-символов \$и <:

    • В заголовке эти символы должны быть экранированы с использованием ведущего символа \ или заключены в диапазоны кода с помощью обратных кавычек (`)

    • В абзаце эти символы должны быть помещены в диапазоны кода. Рассмотрим пример.

      ### The purpose of the \$foo variable

The `$foo` variable is used to store ...

  • Таблицы Markdown

    • Для About_* статей таблицы должны соответствовать 76 символам.
      • Если содержимое не соответствует 76 символьным ограничениям, используйте вместо этого списки маркеров.
    • Использование открытых и закрывающих | символов в каждой строке

Дальнейшие действия

Контрольный список редакции