Документирование новых команд CLI

Эта статья описывает процесс создания документации для новых команд YDB CLI. Она содержит шаблон и рекомендации, основанные на существующих статьях о командах CLI.

Общие принципы

Перед началом работы над документацией новой команды:

Ознакомьтесь с Руководство по стилю документации YDB для понимания общих правил стиля документации.
Убедитесь, что команда реализована и доступна в CLI с опцией --help.

Структура статьи

Каждая статья о команде CLI должна следовать следующей структуре:

1. Заголовок первого уровня

Заголовок должен кратко описывать действие команды. Используйте формулировку, которая начинается с существительного или отглагольного существительного.

Примеры:

# Создание топика
# Удаление таблицы
# Получение статуса фоновой операции
# Чтение из топика

2. Краткое описание

Первые 1–3 предложения описывают назначение команды. Если команда связана с другими командами, добавьте ссылки на них.

Пример:

С помощью подкоманды `topic create` вы можете создать новый топик.

Пример со ссылкой:

С помощью команды `topic consumer add` вы можете добавить читателя для [созданного ранее](topic-create.md) топика.

3. Примечания (опционально)

Если команда имеет важные особенности, ограничения или предупреждения, добавьте их сразу после описания с помощью блока {% note %}.

Пример:

{% note info %}

При удалении топика также будут удалены все добавленные для него читатели.

{% endnote %}

4. Общий вид команды

Покажите синтаксис команды с использованием шаблона ydb и правильного форматирования.

Базовый шаблон:

Общий вид команды:

ydb [global options...] <command> [options...] [arguments...]

* `global options` — [глобальные параметры](commands/global-options.md).
* `options` — [параметры подкоманды](#options).
* `arguments` — аргументы команды (опишите каждый).

Примеры:

Для команды без опций:

ydb [global options...] topic drop <topic-path>

Для команды с опциями:

ydb [global options...] topic create [options...] <topic-path>

Для сложной команды:

ydb [connection options] topic read <topic-path> [--consumer STR] \
  [--format STR] [--wait] [--limit INT] \
  [--transform STR] [--file STR] [--commit BOOL] \
  [дополнительные параметры...]

5. Ссылка на справку

Всегда добавляйте команду для получения справки:

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

ydb <command> --help

6. Параметры подкоманды

Если команда имеет параметры, создайте раздел ## Параметры подкоманды {#options}.

Оформите параметры в виде таблицы:

## Параметры подкоманды {#options}

Имя | Описание
|---|---
`--parameter-name VAL` | Описание параметра.

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

Укажите тип значения, если он важен (например, VAL, STR, INT, BOOL).
Укажите значение по умолчанию, если оно есть.
Перечислите возможные значения для перечислений.
Добавьте ссылки на концепции, если параметр связан с ними.
Используйте HTML-теги для форматирования внутри ячеек таблицы (например, <br/>, <ul>, <li>).

Пример простого параметра:

`--consumer VAL` | Имя читателя, которого нужно добавить.

Пример параметра с описанием:

`--retention-period` | Время хранения данных в топике. Положительное число с указанием единицы измерения.<br/>Поддерживаются следующие единицы:<ul><li>`s` – секунды;</li><li>`m` – минуты;</li><li>`h` – часы;</li><li>`d` – дни.</li></ul>Значение по умолчанию — `18h`.

Пример параметра со ссылкой:

`--partitions-count`| Количество [партиций](../../concepts/datamodel/topic.md#partitioning) топика.<br/>Значение по умолчанию — `1`.

Группировка параметров:

Для команд с большим количеством параметров можно разделить их на группы:

## Параметры {#options}

### Обязательные параметры

`<topic-path>`: Путь топика

### Основные опциональные параметры

`-c VAL`, `--consumer VAL`: Имя читателя топика.

### Другие опциональные параметры

| Имя | Описание |
|-----|----------|
| `--idle-timeout VAL` | Таймаут принятия решения о том что топик пуст. |

7. Примеры

Всегда добавляйте раздел с примерами использования команды.

Шаблон раздела примеров:

## Примеры {#examples}

{% include [ydb-cli-profile](../../_includes/ydb-cli-profile.md) %}

[Описание примера]:

Рекомендации по примерам:

Начинайте каждый пример с краткого описания того, что он демонстрирует.
Используйте профиль quickstart для примеров: ydb -p quickstart ...
Показывайте результаты выполнения команды, если они важны для понимания.
Группируйте связанные примеры.
Добавляйте ссылки на связанные команды или статьи в конце раздела, если это уместно.

Пример простого использования:

Создайте читателя с именем `my-consumer` для [созданного ранее](topic-create.md) топика `my-topic`:

ydb -p quickstart topic consumer add \
  --consumer my-consumer \
  my-topic

Пример с результатом:

Убедитесь, что читатель создан:

ydb -p quickstart scheme describe my-topic

Результат:

    RetentionPeriod: 2 hours
    PartitionsCount: 2
    SupportedCodecs: RAW, GZIP

    Consumers:
    ┌──────────────┬─────────────────┬───────────────────────────────┬───────────┐
    || ConsumerName | SupportedCodecs | ReadFrom                      | Important |
    ├──────────────┼─────────────────┼───────────────────────────────┼───────────┤
    || my-consumer  | RAW, GZIP       | Mon, 15 Aug 2022 16:00:00 MSK | 0         |
    └──────────────┴─────────────────┴───────────────────────────────┴───────────┘

Пример с несколькими вариантами использования:

* Чтение одного сообщения с выводом в терминал:

ydb -p quickstart topic read topic1 -c c1

* Ожидание появления и чтение одного сообщения с записью его в файл:

ydb -p quickstart topic read topic1 -c c1 -w -f message.bin

Полный шаблон статьи

Полный шаблон статьи доступен в отдельном файле: шаблон. Используйте его как основу при создании документации для новой команды CLI.

Специальные случаи

Команды без параметров

Если команда не имеет параметров (кроме глобальных), раздел "Параметры подкоманды" можно опустить.

Пример:

# Удаление топика

С помощью подкоманды `topic drop` вы можете удалить [созданный ранее](topic-create.md) топик.

Общий вид команды:

ydb [global options...] topic drop <topic-path>

* `global options` — [глобальные параметры](commands/global-options.md).
* `topic-path` — путь топика.

Посмотрите описание команды удаления топика:

ydb topic drop --help

## Примеры {#examples}
...

Команды с режимами работы

Если команда поддерживает несколько режимов работы, опишите их перед разделом параметров.

Пример:

Поддерживается три режима работы команды:

1. **Одно сообщение**. Из топика считывается не более одного сообщения.
2. **Пакетный режим**. Сообщения из топика считываются до того момента, пока в топике не закончатся сообщения для обработки.
3. **Потоковый режим**. Сообщения из топика считываются по мере их появления.

Предупреждения об устаревших командах

Если команда устарела, добавьте предупреждение в начале статьи:

{% include notitle [warning](../../reference/ydb-cli/_includes/deprecated_command_warning.md) %}

Именование файлов

Используйте дефисы вместо подчёркиваний: topic-create.md, а не topic_create.md.
Имя файла должно соответствовать структуре команды: topic-consumer-add.md для команды topic consumer add.
Для простых команд используйте короткие имена: version.md, table-drop.md.

Интеграция в документацию

После создания статьи:

Добавьте ссылку в _includes/commands.md — общий список всех команд CLI.
Обновите оглавление — добавьте статью в соответствующий toc_i.yaml или toc_p.yaml.
Добавьте перекрёстные ссылки — обновите связанные статьи, добавив ссылки на новую команду.
Проверьте ссылки — убедитесь, что все внутренние ссылки корректны и используют относительные пути с суффиксом .md.

Проверка перед публикацией

Перед отправкой pull request убедитесь, что:

[ ] Статья следует структуре, описанной выше.
[ ] Все примеры протестированы и работают корректно.
[ ] Используются правильные переменные: ydb, YDB.
[ ] Все ссылки корректны и используют относительные пути с .md.
[ ] Статья добавлена в оглавление и список команд.
[ ] Текст соответствует руководству по стилю.
[ ] Нет опечаток и грамматических ошибок.

См. также

Руководство по стилю документации YDB — общее руководство по стилю документации
Структура документации YDB — структура документации
Процесс ревью документации YDB — процесс ревью документации
Примеры существующих статей — изучите похожие команды для вдохновения

Была ли статья полезна?

Добавление медиа в публичные материалы

Общая схема