Директивы

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

Собирака распознаёт директивы и её аргументы на одном из ранних этапов сборки, однако генерация контента, который подставится вместо директивы, происходит в конце сборки. Это позволяет генерировать контент на основе более полной информации как о текущей, так и обо всех других страницах документации.

@toc #

@toc [--local|--combined] [--depth DEPTH] [--format FORMAT]

Сгенерировать оглавление: иерархический список ссылок на разделы документации. В качестве текста ссылки на каждую страницу используется свойство toc_title или title из её метаданных или заголовок первого уровня.

В зависимости от переданных опций, в список войдут:

• по умолчанию — ссылки на дочерние страницы;
• с опцией --local — ссылки на подразделы текущей страницы;
• с опцией --combined — ссылки на подразделы текущей страницы и на дочерние страницы.

Опция --depth определяет максимальную глубину оглавления. Например, @toc --depth 1 сгенерирует ссылки на страницы или разделы строго одним уровнем ниже текущего.

Опция --format определяет формат отображения номера каждого раздела. Эта опция работает только в документах с включённой автонумерацией.

├── windows.md           →  Установка в Windows
├── windows.md#download  →    Скачайте установщик
├── windows.md#run       →    Запустите установщик
├── macos.md             →  Установка в macOS
├── macos.md#download    →    Скачайте установщик
├── macos.md#run         →    Запустите установщик
├── linux.md             →  Установка в Linux
├── linux.md#download    →    Скачайте установщик
└── linux.md#run         →    Запустите установщик

@manual-toc #

@manual-toc [--local|--combined] [--depth DEPTH] [--ordered] [--unique]

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

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

Поддерживаются два варианта написания директивы. От выбора варианта зависит, на какой участок текста распространяется её действие.

• @manual-toc — проверяется ровно один ближайший блочный элемент: это может быть один абзац, один список, одна таблица и т.п.
• @@manual-toc — проверяются все элементы от текущего места до места нахождения специальной закрывающей директивы @@ (см. пример ниже).

Опции --local, --combined и --depth имеют тот же смысл, что у @toc. Каждая из этих опций влияет на набор ссылок, которые Собирака ожидает увидеть в оглавлении и отсутствие которых будет считаться ошибкой.

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

Если указана опция --unique, то Собирака проверит, чтобы каждая из ожидаемых ссылок была указана ровно один раз.

# Управление пользователями

@@manual-toc --local --ordered --unique

Через интерфейс администратора можно [создавать](#create), [редактировать](#edit) и [удалять](#delete) пользователей.

@@

## Создание пользователей {#create}
## Редактирование пользователей {#edit}
## Удаление пользователей {#delete}

@class #

@class NAME

Присвоить класс NAME следующему блочному элементу: абзацу, таблице, изображению и т.п. Сам по себе класс никак не влияет на отображение в финальном документе, но разработчик расширения может получить класс в коде Python через конструкцию RT.CLASSES[id(elem)] и выполнить ту или иную логику в соответствии с ним.

Например, предположим, что вы хотите применить определённый стиль к таблице терминов и определений. Для этого назначьте класс этой таблице, как показано ниже. После этого в process_table() проверьте значение RT.CLASSES[id(table)], и если оно равно 'TermsAndDefinitions', выполните нужные действия (установите ширину столбцов, выделите первый столбец жирным и т.п.).

@class TermsAndDefinitions

| Термин      | Определение                                             |
|-------------|---------------------------------------------------------|
| Сепульки    | Важный элемент цивилизации ардритов с планеты Энтеропия |
| Сепуление   | Занятие ардритов с планеты Энтеропия                    |
| Сепулькарии | Устройства для сепуления                                |