Участие в документации NemoClaw

Это руководство описывает, как писать, редактировать и рецензировать документацию NemoClaw. Если вы вносите изменения в код, которые влияют на поведение, видимое пользователю, обновите соответствующую документацию в том же PR.

Использование навыков агента

Если вы используете ИИ-агент для написания кода (Cursor, Claude Code, Codex и т.д.), репозиторий содержит навыки, автоматизирующие работу с документацией. Используйте их, прежде чем писать с нуля.

Навыки находятся в .agents/skills/ и автоматически следуют приведённому ниже руководству по стилю. Чтобы использовать навык, попросите вашего агента запустить его. Например, попросите «обновить документацию для всего, что было влито после v0.2.0».

Когда обновлять документацию

Обновляйте документацию, если ваши изменения:

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

Локальная сборка документации

Убедитесь, что документация собирается корректно, выполнив сборку и проверив результат.

Для сборки документации выполните:

make docs

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

make docs-live

Соглашения по написанию

Формат

• Документация использует MyST Markdown — расширение CommonMark, совместимое со Sphinx.
• Каждая страница начинается с YAML frontmatter (title, description, topics, tags, content type).
• Включайте заголовок лицензии SPDX после frontmatter.

Шаблон frontmatter

---
title:
  page: "NemoClaw Page Title — Subtitle with Context"
  nav: "Short Nav Title"
description: "One-sentence summary of the page."
keywords: ["primary keyword", "secondary keyword phrase"]
topics: ["generative_ai", "ai_agents"]
tags: ["openclaw", "openshell", "relevant", "tags"]
content:
  type: concept | how_to | get_started | tutorial | reference
  difficulty: technical_beginner | technical_intermediate | technical_advanced
  audience: ["developer", "engineer"]
status: published
---

Структура страницы

1. Заголовок H1, соответствующий значению title.page.
2. Вводное предложение из одного-двух предложений, описывающее содержание страницы.
3. Разделы, организованные по задачам или концепциям, с использованием H2 и H3. Начинайте каждый раздел с вводного предложения, которое ориентирует читателя.
4. Раздел «Следующие шаги» внизу страницы со ссылками на связанные страницы.

Руководство по стилю

Пишите так, как будто объясняете что-то коллеге. Будьте прямолинейны, конкретны и лаконичны.

Стиль и тон

• Используйте активный залог. «CLI создаёт шлюз», а не «Шлюз создаётся CLI».
• Обращайтесь к читателю на «вы».
• Используйте настоящее время. «Команда возвращает ошибку», а не «Команда будет возвращать ошибку».
• Излагайте факты. Не используйте слова-«костыли» вроде «просто», «легко», «конечно».

Чего избегать

Эти шаблоны характерны для текстов, сгенерированных LLM, и подрывают доверие технических читателей. Удаляйте их при рецензировании.

Правила форматирования

• Завершайте каждое предложение точкой.
• Одно предложение на строку в исходном файле (для удобства чтения диффов).
• Используйте форматирование code для команд CLI, путей файлов, флагов, имён параметров и значений.
• Используйте блоки кода с языком console для примеров CLI. Команды начинайте с $:

  $ nemoclaw onboard

• Используйте таблицы для структурированных сравнений. Таблицы должны быть простыми (без вложенного форматирования).
• Используйте блочные цитаты-предупреждения (> **Note:**, > **Warning:**) для выносок, а не жирный текст.
• Избегайте вложенных предупреждений.
• Не нумеруйте заголовки разделов. Пишите «Развёртывание шлюза», а не «Раздел 1: Развёртывание шлюза» или «Шаг 3: Проверка».
• Не используйте двоеточия в заголовках. Пишите «Развёртывание и управление шлюзами», а не «Шлюзы: развёртывание и управление».
• Используйте двоеточия только для введения списка. Не используйте двоеточия как общую пунктуацию между частями предложения.

Словарь терминов

Используйте единообразно:

Отправка изменений в документацию

1. Создайте ветку в соответствии с соглашением проекта.
2. Внесите изменения.
3. Соберите локально с помощью make docs и проверьте результат.
4. Откройте PR с типом conventional commit docs:.

docs: update quickstart for new onboard wizard

Если изменение документации сопровождает изменение кода, включите оба в один PR и используйте тип коммита для кода:

feat(cli): add policy-add command

Рецензирование PR с документацией

При рецензировании документации:

• Проверяйте соблюдение приведённых выше правил стиля.
• Обращайте внимание на шаблоны, характерные для LLM (чрезмерное выделение жирным, тире, словесный мусор).
• Убедитесь, что примеры кода корректны и исполняемы.
• Проверьте, что перекрёстные ссылки и ссылки не нарушены.
• Соберите локально для проверки отображения.