From 785efd36a2bb017d1863cff87553a9c7ee5577f8 Mon Sep 17 00:00:00 2001 From: orange13 Date: Sat, 15 Nov 2025 22:36:32 +0300 Subject: [PATCH 1/2] initial --- .../_templates/cli-command-template.md | 48 +++ .../cli-command-documentation.md | 321 ++++++++++++++++++ .../core/contributor/documentation/index.md | 3 +- .../core/contributor/documentation/toc_p.yaml | 4 +- 4 files changed, 374 insertions(+), 2 deletions(-) create mode 100644 ydb/docs/ru/core/contributor/documentation/_templates/cli-command-template.md create mode 100644 ydb/docs/ru/core/contributor/documentation/cli-command-documentation.md diff --git a/ydb/docs/ru/core/contributor/documentation/_templates/cli-command-template.md b/ydb/docs/ru/core/contributor/documentation/_templates/cli-command-template.md new file mode 100644 index 000000000000..b57d0441c884 --- /dev/null +++ b/ydb/docs/ru/core/contributor/documentation/_templates/cli-command-template.md @@ -0,0 +1,48 @@ +# [Название действия] + +[Краткое описание назначения команды. Если команда связана с другими, добавьте ссылки.] + +[{% note info/warning %} + +[Примечание, если необходимо] + +{% endnote %}] + +Общий вид команды: + + {{ ydb-cli }} [global options...] [options...] [arguments...] + +* `global options` — [глобальные параметры](commands/global-options.md). +* `options` — [параметры подкоманды](#options). +* `arguments` — [описание аргументов]. + +Посмотрите описание команды: + + {{ ydb-cli }} --help + +## Параметры подкоманды {#options} + +[Если команда имеет параметры, добавьте таблицу или описание] + +Имя | Описание +|---|--- +`--parameter VAL` | Описание параметра. + +## Примеры {#examples} + +{% include [ydb-cli-profile](../../_includes/ydb-cli-profile.md) %} + +[Пример 1]: + + {{ ydb-cli }} -p quickstart [options...] + +[Пример 2 с результатом]: + + {{ ydb-cli }} -p quickstart [options...] + +Результат: + + [Вывод команды] + +[Ссылки на связанные команды или статьи, если необходимо] + diff --git a/ydb/docs/ru/core/contributor/documentation/cli-command-documentation.md b/ydb/docs/ru/core/contributor/documentation/cli-command-documentation.md new file mode 100644 index 000000000000..4165185e6c68 --- /dev/null +++ b/ydb/docs/ru/core/contributor/documentation/cli-command-documentation.md @@ -0,0 +1,321 @@ +# Документирование новых команд CLI + +Эта статья описывает процесс создания документации для новых команд {{ ydb-short-name }} CLI. Она содержит шаблон и рекомендации, основанные на существующих статьях о командах CLI. + +## Общие принципы + +Перед началом работы над документацией новой команды: + +1. Ознакомьтесь с [{#T}](style-guide.md) для понимания общих правил стиля документации. +2. Убедитесь, что команда реализована и доступна в CLI с опцией `--help`. + +## Структура статьи + +Каждая статья о команде CLI должна следовать следующей структуре: + +### 1. Заголовок первого уровня + +Заголовок должен кратко описывать действие команды. Используйте формулировку, которая начинается с существительного или отглагольного существительного. + +**Примеры:** + +- `# Создание топика` +- `# Удаление таблицы` +- `# Получение статуса фоновой операции` +- `# Чтение из топика` + +### 2. Краткое описание + +Первые 1–3 предложения описывают назначение команды. Если команда связана с другими командами, добавьте ссылки на них. + +**Пример:** + +```markdown +С помощью подкоманды `topic create` вы можете создать новый топик. +``` + +**Пример со ссылкой:** + +```markdown +С помощью команды `topic consumer add` вы можете добавить читателя для [созданного ранее](topic-create.md) топика. +``` + +### 3. Примечания (опционально) + +Если команда имеет важные особенности, ограничения или предупреждения, добавьте их сразу после описания с помощью блока `{% note %}`. + +**Пример:** + +```markdown +{% note info %} + +При удалении топика также будут удалены все добавленные для него читатели. + +{% endnote %} +``` + +### 4. Общий вид команды + +Покажите синтаксис команды с использованием шаблона `{{ ydb-cli }}` и правильного форматирования. + +**Базовый шаблон:** + +```markdown +Общий вид команды: + + {{ ydb-cli }} [global options...] [options...] [arguments...] + +* `global options` — [глобальные параметры](commands/global-options.md). +* `options` — [параметры подкоманды](#options). +* `arguments` — аргументы команды (опишите каждый). +``` + +**Примеры:** + +Для команды без опций: + +```markdown + {{ ydb-cli }} [global options...] topic drop +``` + +Для команды с опциями: + +```markdown + {{ ydb-cli }} [global options...] topic create [options...] +``` + +Для сложной команды: + +```markdown + {{ ydb-cli }} [connection options] topic read [--consumer STR] \ + [--format STR] [--wait] [--limit INT] \ + [--transform STR] [--file STR] [--commit BOOL] \ + [дополнительные параметры...] +``` + +### 5. Ссылка на справку + +Всегда добавляйте команду для получения справки: + +```markdown +Посмотрите описание команды: + + {{ ydb-cli }} --help +``` + +### 6. Параметры подкоманды + +Если команда имеет параметры, создайте раздел `## Параметры подкоманды {#options}`. + +Оформите параметры в виде таблицы: + +```markdown +## Параметры подкоманды {#options} + +Имя | Описание +|---|--- +`--parameter-name VAL` | Описание параметра. +``` + +**Рекомендации по описанию параметров:** + +- Укажите тип значения, если он важен (например, `VAL`, `STR`, `INT`, `BOOL`). +- Укажите значение по умолчанию, если оно есть. +- Перечислите возможные значения для перечислений. +- Добавьте ссылки на концепции, если параметр связан с ними. +- Используйте HTML-теги для форматирования внутри ячеек таблицы (например, `
`, `
    `, `
  • `). + +**Пример простого параметра:** + +```markdown +`--consumer VAL` | Имя читателя, которого нужно добавить. +``` + +**Пример параметра с описанием:** + +```markdown +`--retention-period` | Время хранения данных в топике. Положительное число с указанием единицы измерения.
    Поддерживаются следующие единицы:
    • `s` – секунды;
    • `m` – минуты;
    • `h` – часы;
    • `d` – дни.
    Значение по умолчанию — `18h`. +``` + +**Пример параметра со ссылкой:** + +```markdown +`--partitions-count`| Количество [партиций](../../concepts/datamodel/topic.md#partitioning) топика.
    Значение по умолчанию — `1`. +``` + +**Группировка параметров:** + +Для команд с большим количеством параметров можно разделить их на группы: + +```markdown +## Параметры {#options} + +### Обязательные параметры + +``: Путь топика + +### Основные опциональные параметры + +`-c VAL`, `--consumer VAL`: Имя читателя топика. + +### Другие опциональные параметры + +| Имя | Описание | +|-----|----------| +| `--idle-timeout VAL` | Таймаут принятия решения о том что топик пуст. | +``` + +### 7. Примеры + +Всегда добавляйте раздел с примерами использования команды. + +**Шаблон раздела примеров:** + +```markdown +## Примеры {#examples} + +{% include [ydb-cli-profile](../../_includes/ydb-cli-profile.md) %} + +[Описание примера]: +``` + +**Рекомендации по примерам:** + +- Начинайте каждый пример с краткого описания того, что он демонстрирует. +- Используйте профиль `quickstart` для примеров: `{{ ydb-cli }} -p quickstart ...` +- Показывайте результаты выполнения команды, если они важны для понимания. +- Группируйте связанные примеры. +- Добавляйте ссылки на связанные команды или статьи в конце раздела, если это уместно. + +**Пример простого использования:** + +```markdown +Создайте читателя с именем `my-consumer` для [созданного ранее](topic-create.md) топика `my-topic`: + + {{ ydb-cli }} -p quickstart topic consumer add \ + --consumer my-consumer \ + my-topic +``` + +**Пример с результатом:** + +```markdown +Убедитесь, что читатель создан: + + {{ ydb-cli }} -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 | + └──────────────┴─────────────────┴───────────────────────────────┴───────────┘ +``` + +**Пример с несколькими вариантами использования:** + +```markdown +* Чтение одного сообщения с выводом в терминал: + + {{ ydb-cli }} -p quickstart topic read topic1 -c c1 + +* Ожидание появления и чтение одного сообщения с записью его в файл: + + {{ ydb-cli }} -p quickstart topic read topic1 -c c1 -w -f message.bin +``` + +## Полный шаблон статьи + +Полный шаблон статьи доступен в отдельном файле: [шаблон](https://github.com/ydb-platform/ydb/tree/main/ydb/docs/ru/core/contributor/documentation/_templates/cli-command-template.md). Используйте его как основу при создании документации для новой команды CLI. + +## Специальные случаи + +### Команды без параметров + +Если команда не имеет параметров (кроме глобальных), раздел "Параметры подкоманды" можно опустить. + +**Пример:** + +```markdown +# Удаление топика + +С помощью подкоманды `topic drop` вы можете удалить [созданный ранее](topic-create.md) топик. + +Общий вид команды: + + {{ ydb-cli }} [global options...] topic drop + +* `global options` — [глобальные параметры](commands/global-options.md). +* `topic-path` — путь топика. + +Посмотрите описание команды удаления топика: + + {{ ydb-cli }} topic drop --help + +## Примеры {#examples} +... +``` + +### Команды с режимами работы + +Если команда поддерживает несколько режимов работы, опишите их перед разделом параметров. + +**Пример:** + +```markdown +Поддерживается три режима работы команды: + +1. **Одно сообщение**. Из топика считывается не более одного сообщения. +2. **Пакетный режим**. Сообщения из топика считываются до того момента, пока в топике не закончатся сообщения для обработки. +3. **Потоковый режим**. Сообщения из топика считываются по мере их появления. +``` + + +### Предупреждения об устаревших командах + +Если команда устарела, добавьте предупреждение в начале статьи: + +```markdown +{% 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`. + +## Интеграция в документацию + +После создания статьи: + +1. **Добавьте ссылку в `_includes/commands.md`** — общий список всех команд CLI. +2. **Обновите оглавление** — добавьте статью в соответствующий `toc_i.yaml` или `toc_p.yaml`. +3. **Добавьте перекрёстные ссылки** — обновите связанные статьи, добавив ссылки на новую команду. +4. **Проверьте ссылки** — убедитесь, что все внутренние ссылки корректны и используют относительные пути с суффиксом `.md`. + +## Проверка перед публикацией + +Перед отправкой pull request убедитесь, что: + +- [ ] Статья следует структуре, описанной выше. +- [ ] Все примеры протестированы и работают корректно. +- [ ] Используются правильные переменные: `{{ ydb-cli }}`, `{{ ydb-short-name }}`. +- [ ] Все ссылки корректны и используют относительные пути с `.md`. +- [ ] Статья добавлена в оглавление и список команд. +- [ ] Текст соответствует [руководству по стилю](style-guide.md). +- [ ] Нет опечаток и грамматических ошибок. + +## См. также + +- [{#T}](style-guide.md) — общее руководство по стилю документации +- [{#T}](structure.md) — структура документации +- [{#T}](review.md) — процесс ревью документации +- [Примеры существующих статей](../../reference/ydb-cli/index.md) — изучите похожие команды для вдохновения + diff --git a/ydb/docs/ru/core/contributor/documentation/index.md b/ydb/docs/ru/core/contributor/documentation/index.md index 9aa6e0241e05..446beb6c7bc1 100644 --- a/ydb/docs/ru/core/contributor/documentation/index.md +++ b/ydb/docs/ru/core/contributor/documentation/index.md @@ -18,4 +18,5 @@ - [{#T}](genres.md) - [Документация GitHub](https://docs.github.com/en) - [Документация Git](https://git-scm.com/doc) -- [{#T}](guide-to-public-material.md) \ No newline at end of file +- [{#T}](guide-to-public-material.md) +- [{#T}](cli-command-documentation.md) \ No newline at end of file diff --git a/ydb/docs/ru/core/contributor/documentation/toc_p.yaml b/ydb/docs/ru/core/contributor/documentation/toc_p.yaml index 693c0aeeddc8..1ed0024fee73 100644 --- a/ydb/docs/ru/core/contributor/documentation/toc_p.yaml +++ b/ydb/docs/ru/core/contributor/documentation/toc_p.yaml @@ -8,4 +8,6 @@ items: - name: Жанры href: genres.md - name: Добавление медиа в публичные материалы - href: guide-to-public-material.md + href: guide-to-public-material.md +- name: Документирование новых команд CLI + href: cli-command-documentation.md From 19c7f23adc1583476bb23f6db9b7e71e6f065e9e Mon Sep 17 00:00:00 2001 From: orange13 Date: Mon, 17 Nov 2025 09:24:52 +0300 Subject: [PATCH 2/2] Update cli-command-documentation.md --- .../cli-command-documentation.md | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/ydb/docs/ru/core/contributor/documentation/cli-command-documentation.md b/ydb/docs/ru/core/contributor/documentation/cli-command-documentation.md index 4165185e6c68..eca3d39bc09d 100644 --- a/ydb/docs/ru/core/contributor/documentation/cli-command-documentation.md +++ b/ydb/docs/ru/core/contributor/documentation/cli-command-documentation.md @@ -63,7 +63,7 @@ ```markdown Общий вид команды: - {{ ydb-cli }} [global options...] [options...] [arguments...] +{{ ydb-cli }} [global options...] [options...] [arguments...] * `global options` — [глобальные параметры](commands/global-options.md). * `options` — [параметры подкоманды](#options). @@ -75,22 +75,22 @@ Для команды без опций: ```markdown - {{ ydb-cli }} [global options...] topic drop +{{ ydb-cli }} [global options...] topic drop ``` Для команды с опциями: ```markdown - {{ ydb-cli }} [global options...] topic create [options...] +{{ ydb-cli }} [global options...] topic create [options...] ``` Для сложной команды: ```markdown - {{ ydb-cli }} [connection options] topic read [--consumer STR] \ - [--format STR] [--wait] [--limit INT] \ - [--transform STR] [--file STR] [--commit BOOL] \ - [дополнительные параметры...] +{{ ydb-cli }} [connection options] topic read [--consumer STR] \ + [--format STR] [--wait] [--limit INT] \ + [--transform STR] [--file STR] [--commit BOOL] \ + [дополнительные параметры...] ``` ### 5. Ссылка на справку @@ -100,7 +100,7 @@ ```markdown Посмотрите описание команды: - {{ ydb-cli }} --help +{{ ydb-cli }} --help ``` ### 6. Параметры подкоманды @@ -192,9 +192,9 @@ ```markdown Создайте читателя с именем `my-consumer` для [созданного ранее](topic-create.md) топика `my-topic`: - {{ ydb-cli }} -p quickstart topic consumer add \ - --consumer my-consumer \ - my-topic +{{ ydb-cli }} -p quickstart topic consumer add \ + --consumer my-consumer \ + my-topic ``` **Пример с результатом:** @@ -202,7 +202,7 @@ ```markdown Убедитесь, что читатель создан: - {{ ydb-cli }} -p quickstart scheme describe my-topic +{{ ydb-cli }} -p quickstart scheme describe my-topic Результат: @@ -223,11 +223,11 @@ ```markdown * Чтение одного сообщения с выводом в терминал: - {{ ydb-cli }} -p quickstart topic read topic1 -c c1 +{{ ydb-cli }} -p quickstart topic read topic1 -c c1 * Ожидание появления и чтение одного сообщения с записью его в файл: - {{ ydb-cli }} -p quickstart topic read topic1 -c c1 -w -f message.bin +{{ ydb-cli }} -p quickstart topic read topic1 -c c1 -w -f message.bin ``` ## Полный шаблон статьи @@ -249,14 +249,14 @@ Общий вид команды: - {{ ydb-cli }} [global options...] topic drop +{{ ydb-cli }} [global options...] topic drop * `global options` — [глобальные параметры](commands/global-options.md). * `topic-path` — путь топика. Посмотрите описание команды удаления топика: - {{ ydb-cli }} topic drop --help +{{ ydb-cli }} topic drop --help ## Примеры {#examples} ...