feat: check sorting in reference/cli.md

Описание

Добавлен хук check_sorting.py, который проверяет порядок следования подзаголовков --<option> на странице cli.md.

Порядок должен быть алфавитным, иначе в лог MkDocs будет выведена следующая запись со статусом WARNING:

WARNING -  check_sorting: INCORRECT SORTING @ reference/cli.md: ## picodata run {: #run }

Алгоритм:

1. Хук выполняется в событии on_page_markdown только для страницы cli.md
2. Из заголовков уровней h2 и h3 формируется словарь index формата dict[h2, list[h3]]
3. Проверяются значения словаря index: если список list[h3] не отсортирован по алфавиту, об этом выводится запись в лог MkDocs

Списки list[h3] формируются из опций формата --<option>, поэтому для данного хука следующий список отсортирован не по алфавиту:

### -a, --auth-type {: #connect_auth_type }
### -u, --user {: #connect_user }
### --password-file {: #connect_password_file }

Отсортированный список:

### -a, --auth-type {: #connect_auth_type }
### --password-file {: #connect_password_file }
### -u, --user {: #connect_user }

See:

• https://www.mkdocs.org/dev-guide/plugins/#events

---

• Close #190 (closed)
• Target branch: main
• Changes should be cherry-picked to 24.1: NO
• Staging: https://docs.binary.picodata.io/picodata/branch-check-alphabetical-order/

assigned to @a.sabirov

added 1 deleted label

added docs: improve label

changed the description

added 1 commit

• 8cdaad89 - feat: check the order of subheaders in cli.md

Compare with previous version

changed the description

Проверил: да, хук работает согласно описанию. Но меня смущает пара моментов:

1. Отсортированный список в данном случае выглядит менее аккуратно:

### -a, --auth-type {: #connect_auth_type }
### --password-file {: #connect_password_file }
### -u, --user {: #connect_user }

Просится короткий вариант (-p, если он не занят), но это тянет изменение в самой Picodata

2. Соответственно, у меня предложение: м.б., не делать явное ограничение на cli.md, а сделать так, чтобы этот хук смотрел во все *.md, но срабатывал только если у списка h2 есть явный маркер сортировки своих элементов? То есть, мы явно задаем списки, которые мы хотим проверить на корректность сортировки.

removed docs: improve label

added docs: rearrange label

changed the description

added 1 commit

• bc951166 - feat: check the order of subheaders in cli.md

Compare with previous version

added 1 commit

• 56f617ea - feat: check sorting in reference/cli.md

Compare with previous version

added 1 commit

• 6b3a65a1 - feat: check sorting in reference/cli.md

Compare with previous version

added 1 commit

• f85b547c - feat: check sorting in reference/cli.md

Compare with previous version

added 5 commits

• f85b547c...591cdcfe - 3 commits from branch main
• 36d0a92f - feat: check sorting in reference/cli.md
• b231b178 - cli.md: fix sorting and minor edits

Compare with previous version

changed title from feat: check the order of subheaders in cli.md to feat: check sorting in reference/cli.md

changed the description

approved this merge request