Cluster · разработчикам

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

У каждой версии модуля может быть своя документация. Она открывается на странице модуля в каталоге, в установленном экземпляре и при проверке версии в админке. Список команд строится по описанию интерфейса.

Документация

Добавь documentation в manifest.json. Значение содержит сам текст в Markdown:

{
    "documentation": "# Заметки\n\nМодуль сохраняет короткие заметки.\n\n## Использование\n\nОтправь `!note текст` для создания заметки."
}

В полном описании пакета по-прежнему нужны название, описание, версия, права, зависимости и история изменений. Здесь показано только новое поле. documentation необязательно: прежние модули продолжают работать без него. Если документация не нужна, убери поле, а не передавай пустую строку.

Максимальный размер текста 64 KiB в UTF-8. Для двух языков можно передать объект:

{
    "documentation": {
        "ru": "# Заметки\n\nСохраняет заметки в данных модуля.",
        "en": "# Notes\n\nStores notes in the module data."
    }
}

В таком объекте обязательны обе непустые строки, каждая до 64 KiB. На сайте язык выбирается вместе с языком интерфейса. Если передана одна строка, она показывается на обоих языках.

Поддерживаются заголовки, списки, таблицы, ссылки, цитаты и блоки кода. HTML не выполняется, внешние картинки не загружаются. Для ссылок подходят HTTP, HTTPS и mailto:. Относительные ссылки на файлы внутри архива не превращаются в публичные адреса: используй полный адрес доступного руководства.

Описание команды в коде

У декоратора команды появились необязательные description и usage:

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from router import Event

class Module:
    @loader.command(
        "note",
        source="both",
        access="owner",
        description={"ru": "Сохранить заметку", "en": "Save a note"},
        usage="<text>",
    )
    async def note(self, ctx: Event) -> None:
        await ctx.app.db.set("last", ctx.args)
        await ctx.reply("Saved.")

description содержит короткое объяснение команды, до 2048 байтов UTF-8. usage содержит только аргументы, до 512 байтов. Оба значения принимают строку или объект с ru и en.

Префикс и название команды в usage указывать не нужно. Для исходного алиаса note сайт покажет !note <text>, а после замены алиаса на save и префикса на . покажет .save <text>. Если команда также работает через бота, отдельно появится /save <text>.

Квадратные и угловые скобки здесь только соглашение автора для справки. Они не создают проверку аргументов: разбор ctx.args остаётся в обработчике.

Описание интерфейса

Те же поля можно указать в interface.commands файла описания:

{
    "interface": {
        "commands": [
            {
                "id": "note",
                "alias": "note",
                "source": "both",
                "access": "owner",
                "description": {"ru": "Сохранить заметку", "en": "Save a note"},
                "usage": "<text>"
            }
        ]
    }
}

При публикации сохраняется это описание версии. Текст справки из опубликованного описания имеет приоритет при показе на сайте. Его можно дополнить в редакторе публикации без изменения исходника обработчика.

Во время запуска ядро по-прежнему сверяет реальные команды, алиасы, источники событий, права, поля и страницы с установленной версией. Различия только в description и usage не мешают запуску. Справка не создаёт обработчики и не меняет доступ к ним.

Публикация через сайт

На форме новой версии есть раздел «Документация и команды»:

  1. Введи документацию в Markdown.
  2. При необходимости добавь перевод.
  3. Раскрой нужную команду и заполни описание и аргументы обычными полями.
  4. Открой предварительный просмотр.
  5. Опубликуй версию вместе с остальными сведениями и архивом модуля.

Список доступных для описания команд берётся из поля интерфейса. Добавление команды только в справку не создаёт её в Python-коде. Исполняемые команды должны быть объявлены в самом модуле.

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

Просмотр

В каталоге вкладка «Документация и команды» позволяет переключаться между версиями. У установленного экземпляра показывается документация его версии, даже если автор уже выпустил более новую.

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

HTTP-метод interface/view возвращает переведённый текст в documentation, а описания и аргументы в элементах commands. Доступ к установленному экземпляру проверяется как прежде. catalog/detail и catalog/versions возвращают документацию внутри manifest соответствующего выпуска.