Профили¶

Профиль адаптирует набор правил под требования кафедры без форка репозитория: отключает правила, меняет их уровень, задаёт параметры.

nk check chapters --profile profiles/my-department.toml

Без ключа профиль ищется рядом с исходниками, а если не найден — применяется встроенный base: все правила с их объявленными уровнями.

Где лежит профиль¶

Ключ --profile не обязателен: nk поднимается от проверяемых путей вверх по дереву каталогов и берёт первый найденный файл.

Файл	Секция
`nk.toml`	весь файл
`.nk.toml`	весь файл
`pyproject.toml`	`[tool.nk]`

В одном каталоге порядок такой же: nk.toml перед .nk.toml, оба — перед pyproject.toml. Файл pyproject.toml без секции [tool.nk] пропускается, поиск продолжается выше: чужая сборка не должна выдавать себя за профиль.

Поиск начинается с общего каталога всех проверяемых путей — профиль на прогон один, иначе части исходников проверялись бы по разным правилам. Явный --profile отменяет поиск.

В pyproject.toml ключи профиля те же, только с префиксом секции:

[tool.nk]
name = "Кафедра N"
disable = ["figure-reference-word"]

[tool.nk.rules."keywords-count".params]
keywords_max = 20

[tool.nk.elements.aliases]
"СПИСОК ЛИТЕРАТУРЫ" = "СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ"

Какой файл подхватился, показывает nk profile show строкой «Файл».

Формат¶

name = "Кафедра N"
extends = "base"

# Отключить правила целиком.
disable = ["figure-reference-word"]

# Понизить уровень: нарушение показывается, но не влияет на код возврата.
[rules."heading-depth"]
severity = "info"

# Поднять уровень.
[rules."table-reference-word"]
severity = "error"

# Переопределить параметры. Незаданные берутся из объявления правила.
[rules."keywords-count".params]
keywords_max = 20

# Наименования структурных элементов, принятые кафедрой вместо стандартных.
[elements.aliases]
"СПИСОК ЛИТЕРАТУРЫ" = "СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ"

Ключ	Значение
`name`	имя профиля, попадает в шапку вывода
`extends`	профиль-основа: имя встроенного либо файл рядом; цепочкой
`standard`	стандарт, пункты которого попадают в находки
`source.title`	название своего источника требований
`disable`	идентификаторы правил, которые не запускаются
`enable`	идентификаторы правил, выключенных по умолчанию
`rules."ID".severity`	`error`, `warning` или `info` вместо объявленного
`rules."ID".clause`	пункт своего источника вместо пункта стандарта
`rules."ID".params`	значения параметров правила
`elements.order`	состав и порядок структурных элементов
`elements.roles`	роли элементов: какой элемент чем является для правил
`elements.aliases`	наименования элементов кафедры и их канонические наименования
`appendix.letters`	обозначения приложений по порядку

Готовый образец для копирования — profiles/example-university.toml.

Структурные элементы¶

Наименования элементов — общий словарь всех правил о структуре: состав, порядок, регистр заголовков, содержание реферата. Если кафедра называет элемент иначе, чем стандарт, наименование объявляется синонимом:

[elements.aliases]
"СПИСОК ЛИТЕРАТУРЫ" = "СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ"
"ОБОЗНАЧЕНИЯ И СОКРАЩЕНИЯ" = "ПЕРЕЧЕНЬ СОКРАЩЕНИЙ И ОБОЗНАЧЕНИЙ"

Слева — как пишет кафедра, справа — каноническое наименование; регистр и знаки препинания значения не имеют. Наименование справа проверяется по составу: синоним, ведущий к тому, чего в составе нет, — ошибка профиля, иначе опечатка молча выключала бы опознание элемента.

Состав и порядок¶

Кафедре синонимов обычно хватает. Другой источник требований — другой ГОСТ, положение вуза — задаёт свои состав и порядок целиком:

[elements.order]
"ПРЕДИСЛОВИЕ" = 1
"СОДЕРЖАНИЕ" = 2
"ОБОЗНАЧЕНИЯ И СОКРАЩЕНИЯ" = 3
"ТЕРМИНЫ И ОПРЕДЕЛЕНИЯ" = 4
"ВВЕДЕНИЕ" = 5
"ЗАКЛЮЧЕНИЕ" = 6
"ПРИЛОЖЕНИЕ" = 7

Наименования в TOML пишутся в кавычках: ключ из кириллицы иначе не разбирается.

Число — ранг, место элемента в порядке. Общий ранг у элементов, которые занимают одно место и заменяют друг друга: отдельный перечень терминов и объединённый перечень терминов и сокращений идут под одним номером.

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

Порядок из профиля попадает и в текст находки: правило elements-order называет тот порядок, по которому проверяется этот отчёт.

Роли¶

Правило спрашивает словарь не про наименование, а про роль: не «это РЕФЕРАТ?», а «это элемент, где ведут реферат?». Наименование под ролью задаёт профиль:

[elements.roles]
abstract = ["РЕФЕРАТ"]
contents = ["СОДЕРЖАНИЕ"]
terms = ["ТЕРМИНЫ И ОПРЕДЕЛЕНИЯ"]
abbreviations = ["ПЕРЕЧЕНЬ СОКРАЩЕНИЙ И ОБОЗНАЧЕНИЙ", "ОПРЕДЕЛЕНИЯ ОБОЗНАЧЕНИЯ И СОКРАЩЕНИЯ"]
bibliography = ["СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ"]
appendix = ["ПРИЛОЖЕНИЕ"]

Роль	Кто её спрашивает
`abstract`	правила о составе и оформлении реферата
`contents`	зачёт содержания по `\tableofcontents`
`terms`	перечень терминов: порядок, вводная фраза, тире
`abbreviations`	перечень сокращений: свой либо объединённый
`bibliography`	зачёт списка источников по окружению библиографии
`appendix`	опознание заголовка «ПРИЛОЖЕНИЕ А»

Роль может занимать несколько наименований и может пустовать. Пустая роль — не ошибка: у источника требований, где нет реферата, правила о реферате молчат.

Без секции roles роли берутся по умолчанию, но только теми наименованиями, которые остались в составе. Роль, названная явно, заменяет умолчание целиком, а наименование в ней обязано быть в order.

Состав обязательных элементов задаётся параметрами правила required-element-missing. Убрать одно требование, оставив остальные:

[rules."required-element-missing".params]
excluded = ["РЕФЕРАТ"]

Задать перечень целиком:

[rules."required-element-missing".params]
required = ["СОДЕРЖАНИЕ", "ВВЕДЕНИЕ", "ЗАКЛЮЧЕНИЕ", "СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ"]

В обоих списках наименования пишутся по стандарту либо синонимами кафедры. Наименование, которого нет ни там ни там, проверку не выключает: элемент просто не найдётся, и правило сообщит о его отсутствии — опечатка в профиле остаётся видимой.

Стандарт и свой источник требований¶

Одно и то же требование записано в нескольких стандартах под разными пунктами. Какой из них попадёт в находку, решает профиль:

standard = "G732"

Значение	Стандарт
`G732`	ГОСТ 7.32-2017, по умолчанию
`GR2105`	ГОСТ Р 2.105-2019

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

Правило, требования которого в выбранном стандарте нет, не запускается: отчёт по одному стандарту иначе получал бы находки по чужому. Под gost-r-2.105 молчат правила о реферате и ключевых словах — их требует только ГОСТ 7.32.

Привлечённый стандарт¶

Стандарт бывает не активным, а привлечённым: положение МГТУ велит оформлять список источников по ГОСТ Р 7.0.100-2018 (п. 10.10), а отчёт при этом остаётся отчётом по ГОСТ 7.32-2017. Заменять один стандарт другим тут нечем — под ГОСТ Р 7.0.100 замолчали бы все правила, кроме правил о библиографическом описании. Поэтому такой стандарт не выбирают, а привлекают:

standard = "G732"
references = ["GR70100"]

Значение	Стандарт
`GR70100`	ГОСТ Р 7.0.100-2018

Пункты привлечённого стандарта действуют наравне с пунктами активного: правила, у которых пункт есть только там, начинают работать, а находки ссылаются на его пункты. Ищут пункт сначала в активном стандарте — там, где требование записано в обоих, отчёт оформляют по активному.

Привлечённые стандарты, в отличие от активного, накапливаются по цепочке extends: профиль кафедры дописывает свои к тем, что привлёк профиль вуза.

Общее требование — типографика — работает под любым профилем, даже если у какого-то стандарта под него есть пункт. Так устроен unit-nbsp: неразрывный пробел между числом и единицей нужен в любом отчёте, а под gost-r-2.105 находка вдобавок ссылается на пункт.

Третий случай — требование положения вуза: figure-reference-form, heading-rubric-word, правила об изложении от первого лица. Стандарт их не предписывает, поэтому от его выбора они не зависят, а чьи они — говорит профиль. Назвав [source] title, профиль называет источник и в тех находках, для которых пункта не объявил: «требует положение МГТУ» полезнее, чем молчание. Чьё требование проверяет правило, видно в колонке «Источник» обзора правил и в выводе nk rules show.

Подключить требование из другого стандарта — если так велит положение вуза — можно ключом enable:

enable = ["keywords-count"]

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

[source]
title = "Положение МГТУ им. Н.Э. Баумана № 01-01-ПЛ-016 01-2024"

[rules."appendix-sequence"]
clause = "10.11"

Пункт, объявленный профилем, старше пункта стандарта. Объявить пункт, не назвав источник, нельзя: непонятно, чей он.

Обозначения приложений¶

Обозначения приложений — знаки строки, идущие по порядку:

[appendix]
letters = "123456789"

По умолчанию это прописные буквы кириллицы без Ё, З, Й, О, Ч, Ъ, Ы и Ь. Готовые наборы — латиница без I и O, арабские цифры — выписаны в комментариях встроенного профиля base, откуда их копируют.

Набор задаёт и допустимые обозначения, и их порядок, и то, какой номер получит рисунок или таблица внутри приложения. Повтор знака — ошибка профиля: по обозначению определяется место приложения в последовательности, а у повторённого знака мест было бы два.

Набор один. Если источник требований допускает две системы обозначений — скажем, и цифры, и латиницу, — выбрать в профиле придётся одну.

Готовые профили¶

Кроме base в поставку входит профиль под положение вуза:

nk check chapters --profile bmstu-vkr

Профиль	Что описывает
`base`	чистый ГОСТ 7.32-2017, все правила с объявленными уровнями
`bmstu-vkr`	ВКР по положению МГТУ им. Н.Э. Баумана № 01-01-ПЛ-016 01-2024
`gost-r-2.105`	текстовый документ ЕСКД по ГОСТ Р 2.105-2019

bmstu-vkr показывает, как настраивается источник требований, который ссылается на ГОСТ, но расходится с ним в частностях: свой состав элементов, объединённый перечень обозначений и сокращений, реферат без ключевых слов, приложения под цифрами, разделы основной части без разрыва страницы. Пункты в находках остаются пунктами 7.32.

Профиль кафедры наследуется от готового и правит своё:

name = "Кафедра ИУ-N"
extends = "bmstu-vkr"

disable = ["figure-reference-word"]

Наследование¶

extends образует цепочку любой длины: профиль кафедры наследуется от профиля вуза, тот — от профиля стандарта. Ближний профиль сильнее дальнего.

Ссылка ищется относительно того файла, где написана, поэтому профиль кафедры может ссылаться на соседний файл, а тот — на встроенный. Замкнувшаяся цепочка — ошибка профиля, а не бесконечный цикл: nk называет её целиком.

Отсюда способ не повторять --profile в каждой команде — положить рядом с исходниками nk.toml:

name = "ВКР"
extends = "bmstu-vkr"

Профиль подхватится сам: nk поднимается вверх по дереву каталогов от проверяемых путей.

Правила, выключенные по умолчанию¶

Часть правил выключена по умолчанию — те, что дают много находок или ложно срабатывают там, где по исходникам не разобраться. Включаются они явно:

enable = ["preposition-nbsp"]

Выключение не связано с источником требования: выключенными по умолчанию бывают и типографика (preposition-nbsp — находок много), и требование стандарта (enumeration-lowercase — имя собственное в начале элемента перечисления от обычного слова не отличить), и требование положения (figure-reference-form, heading-rubric-word — у каждого вуза свои).

На странице такого правила стоит пометка о том, что оно выключено. Ключ --select тоже включает их: nk check chapters --select preposition-nbsp.

Проверка профиля¶

Опечатка в идентификаторе правила — ошибка, а не молчаливое отключение проверки: профиль, ссылающийся на несуществующее правило, не запускается.

Посмотреть, что получилось после наследования и переопределений:

nk profile show --profile profiles/my-department.toml

Команда печатает файл профиля, действующие стандарты, итоговый уровень каждого правила, состояние и параметры. Без ключа --profile профиль ищется от текущего каталога.

Профиль: МГТУ, ВКР
Файл: встроенный
Стандарт: ГОСТ 7.32-2017
Привлечены: ГОСТ Р 7.0.100-2018
Свой источник: Положение МГТУ им. Н.Э. Баумана № 01-01-ПЛ-016 01-2024
Правил включено: 76 из 96
Не запускаются: 6 — отключено профилем, 13 — нет в стандарте, 1 — выключено по умолчанию
ID                               Уровень  Состояние           Источник                Параметры
abbreviations-final-punctuation  warning  включено            свой источник п. 10.9
bibitem-area-separator           error    включено            ГОСТ Р 7.0.100-2018 п. 4.6.2
formula-sequence-comma           warning  включено профилем   свой источник п. 10.7
keywords-count                   error    отключено профилем                          keywords_max=15

Состояние называет причину, а не только ответ: правило молчит чаще не потому, что его выключили, а потому, что его требования нет в стандарте прогона.

Состояние	Что это значит
`включено`	правило работает
`включено профилем`	подключено ключом `enable` вопреки умолчанию
`отключено профилем`	перечислено в `disable`
`нет в стандарте`	требование не записано ни в активном стандарте, ни в привлечённых
`выключено по умолчанию`	правило из тех, что включают явно

Колонка «Источник» появляется только у профиля, который расходится со стандартом: в ней те правила, чей пункт взят из привлечённого стандарта или из своего источника. Пункт активного стандарта в ней не повторяется — он назван в шапке и на странице правила.

Что настраивать имеет смысл¶

Требования кафедры расходятся со стандартом. Например, принято сокращение «рис.» в ссылках: правило figure-reference-word отключается.
Пороги. Диапазон числа ключевых слов, предельная глубина рубрикации — параметры, а не константы.
Наименования и состав структурных элементов. Кафедра пишет «СПИСОК ЛИТЕРАТУРЫ» или не требует реферата — это синонимы и excluded, а не отключение правила целиком.
Строгость сборки. Уровень определяет, падает ли CI: error — да, warning и info — нет.

Параметры каждого правила перечислены на его странице в разделе Правила.