Локальный сайт справочника

Требуется Python 3 с venv и pip на Windows 11. Node.js не нужен. При первой установке зависимостей необходим доступ к PyPI или настроенному зеркалу.

В PowerShell из корня репозитория:

powershell -ExecutionPolicy Bypass -File .\start-docs.ps1

Откройте http://127.0.0.1:8000. Остановить сервер можно клавишами Ctrl+C. Скрипт создаёт .venv-docs, устанавливает зависимости из requirements-docs.txt и запускает сервер только на localhost. Изменения исходных файлов автоматически пересобирают страницы.

Для проверки сборки:

.\.venv-docs\Scripts\python.exe -m mkdocs build --strict

Для автономной сборки на Linux или macOS из корня репозитория:

python3 -m venv .venv-docs
.venv-docs/bin/python -m pip install -r requirements-docs.txt
.venv-docs/bin/python -m mkdocs build --strict

Навигация создаётся хуком docs_hooks/navigation.py из Markdown-файлов в каталогах 01–07 и glossary, включая вложенные папки; заголовком служит первый заголовок первого уровня. README.md раздела становится его обзором. Добавление статей не требует редактирования mkdocs.yml. Хук включает читательские страницы, выбранные источники и файлы учебных примеров по явным правилам. Архивные ссылки отображаются текстом. Новые типы ресурсов и JSON-примеры добавляются в список разрешённых файлов.

MkDocs получает публичные страницы и ресурсы через API File; docs_shell содержит локальную библиотеку Mermaid 11.17.2 и её лицензию. Сгенерированный site/ и окружение .venv-docs/ исключены из Git. Индекс поиска и JavaScript включаются в сборку; браузер должен разрешать JavaScript.