Для проверки новой (и существующей) документации на опечатки мы решили прикрутить к сайту спелл-чекер, который бы все это делал автоматически сразу на GitHub в Pull-реквестах.
Решение было найдено случайно, когда я открыл Vim и вспомнил, как настраивал там проверку орфографии.
Как это работает
Подробности можно найти в этом PR.
Суть работы заключается в следующем:
- Сам сайт генерируется Jekyll’ом в обычном режиме. Так как некоторая часть генерируется предварительно в других контейнерах и копируется в конечный, это решение позволяет проверять сразу полноценный конечный вариант документации.
- Заходим в контейнер и делаем следующее:
- Убираем из всех HTML-страниц блоки с кодом (
<code></code>); - Очищаем HTML страницы от тегов и получаем plain text;
- Немного фиксим ошибки, возникшие в процессе (например, удаляем пустые строки);
- Натравливаем hunspell на каждый файл.
- Убираем из всех HTML-страниц блоки с кодом (
В результате получается список терминов, которых нет в словарях (они считаются опечатками).
Для учета слов, которых нет в готовых словарях английского с русского языков (DevOps-термины, например), сгенерен свой словарь терминов, которые постепенно будет наполняться.
Пример выхлопа можно посмотреть тут.
Запускать проверку можно как для всех страниц сразу, так и выборочно для EN или РУ-версии (это отдельные контейнеры).
Updates
- Добавлена проверка одного конкретного файла, который можно указать в аргументах команды запуска. Подробности в этом PR.
- Добавлены три команды для выдергивания общего списка опечаток в сортированном виде. Подробности в этом PR.
- Добавлено управление сборкой через ENV, чтобы образ спеллчекера не собирался при деплое сайта в прод. Подробности в этом PR.
- Добавлено удаление блоков кода, добавляемых через сниппеты (div с классом
snippetcut). Подробности в этом PR. - Добавлены (PR):
- кастомный словарь терминов (заполнен найденными ранее «опечатками», которых нет в базовых словарях), исключая сомнительные термины;
- добавлена команда для вывода очищенного от HTML-тегов содержимого конкретного файла.
- Исправлен предыдыдущий: было прибито гвоздями отображение только англ. версии в plain text. PR
- Небольшой фикс сборки. PR
- Исправлен порядок сборки: теперь нужные стадии должны кешироваться, а не пересобираться каждый раз. PR
- Добавлена индикация языка файла для общей проверки. PR
- Добавлен механизм исключения файлов или каталогов из проверки. PR
- Добавлена возможность исключать из проверки блоки HTML, выделив их соответствующими коментариями. PR