Сборка и проверка документации¶
Для сборки документации нужен Python 3.11+ (требование sphinx-design 0.7). Сама библиотека поддерживает Python 3.10+. Из корня репозитория выполните:
uv sync --locked --group docs
uv run --no-sync python -m sphinx -E -a -n -W --keep-going -b html -D language=ru docs docs/_build/html/ru
uv run --no-sync python -m sphinx -E -a -n -W --keep-going -b html -D language=en docs docs/_build/html/en
uv run --no-sync python -m sphinx -E -a -n -W --keep-going -b doctest -D language=ru docs docs/_build/doctest/ru
uv run --no-sync python -m sphinx -E -a -n -W --keep-going -b doctest -D language=en docs docs/_build/doctest/en
uv run --no-sync python -m sphinx -E -a -n -W --keep-going -b gettext docs docs/_build/gettext
uv run --no-sync python docs/check.py
Русская версия находится в docs/_build/html/ru/index.html, английская —
в docs/_build/html/en/index.html. При HTML-сборке в каталог ru или en
рядом автоматически создаётся общий index.html. Публикуйте весь каталог
docs/_build/html: общий вход выбирает русский для основного языка браузера
ru или ru-*, английский — для остальных языков и при отсутствии настройки.
Прямые ссылки на ru/ и en/ не перенаправляются; переключатель языка
открывает ту же страницу соседней версии. Без JavaScript на общем входе
доступны ссылки на оба языка.
-E -a заставляет
перечитать все исходники, -n проверяет ссылки на API, -W превращает
предупреждения в ошибки. --keep-going собирает все найденные проблемы
за один запуск. Для Python intersphinx нужен доступ к
https://docs.python.org/3/objects.inv; ошибка его загрузки тоже прерывает
строгую проверку.
Doctest исполняет примеры, проверяя assertions и точный вывод, включая hex.
docs/check.py дополнительно проверяет файлы и anchors внутренних
HTML-ссылок, включая переходы между языками, наличие целей для публичных
exports в каждой версии, полноту перевода по свежим gettext-каталогам,
относительные README-ссылки и Python-пример README. Комментарии у print в README задают ожидаемый
вывод. Проверка локальных ссылок не обращается к внешним сайтам.
Как добавлять примеры¶
Используйте testcode для обычного Python-кода и testoutput для
ожидаемого вывода. Несколько блоков на странице могут продолжать один пример;
независимым сценариям можно назначить отдельные группы. :hide: скрывает
ожидаемый вывод, но не отключает его проверку. Примеры без вывода проверяйте
через assert. Вычисляйте hex исполнением примера, затем фиксируйте
ожидаемое значение в документации.
Construct нужен только для исполняемого сравнения на Зачем bytespec?.
Он включён в группу docs и не является runtime-зависимостью bytespec.
Не заменяйте его пример непроверяемым псевдокодом.
Конфигурация использует Sphinx, Furo, autodoc и явный перечень публичных
точек входа. conf.py добавляет src в путь импорта; после установки
зависимостей команды можно запускать через .venv/bin/python.
Версия берётся из metadata дистрибутива, а без установки — из
pyproject.toml через tomllib (для этого fallback нужен Python 3.11+).
Требование самой библиотеки — Python 3.10+.
Как обновлять перевод¶
Исходные .rst написаны на русском, docstrings библиотеки — на английском.
Английский перевод страниц хранится в docs/locale/en/LC_MESSAGES/*.po
и подкаталоге api/. Русский перевод docstrings для API находится в
docs/locale/ru/LC_MESSAGES/api/*.po. Sphinx применяет переводы при сборке;
docstrings в установленной библиотеке всегда остаются английскими.
После изменения исходников обновите каталоги:
uv run --no-sync python -m sphinx -E -a -n -W --keep-going -b gettext docs docs/_build/gettext
uv run --no-sync sphinx-intl update -p docs/_build/gettext -d docs/locale -l en -l ru
Переведите новые msgstr и проверьте строки с пометкой fuzzy;
после проверки уберите эту пометку. Не меняйте msgid, имена API,
цели ссылок и wire-значения. При переводе кода сохраняйте согласованность
с testoutput: скрытый ожидаемый вывод общий для обоих языков.
Затем повторите обе HTML- и doctest-сборки и docs/check.py.
Sphinx сам компилирует .po в .mo; сгенерированные .mo и _build
не хранятся в репозитории. sphinx-intl нужен только для сопровождения
переводов и входит в группу docs.
Элементы интерфейса в RST¶
Используйте tab-set с вкладками Python, Байты и Разбор только там,
где полезно сопоставить код с результатом. testcode и testoutput
внутри вкладок по-прежнему исполняются doctest, даже если вкладка скрыта.
Независимым примерам задавайте одинаковое имя группы у кода и ожидаемого вывода.
Для разбора байтов используйте container:: wire-bytes с короткими
dropdown внутри. Номер, имя поля и hex находятся в заголовке, объяснение —
в раскрываемой части. Для пояснений к коду используйте тот же приём с
container:: code-notes; номера остаются вне копируемого Python-кода.
Схема заголовка использует grid с классом wire-layout.
Общие стили находятся в _static/interactive.css; raw HTML не нужен.
Пример повторяемого блока:
.. container:: wire-bytes
.. dropdown:: ① value · ``00 00 00 2a``
UInt32: 42, four bytes.
Текст интерфейса пишется в RST и попадает в gettext. После изменения примеров проверяйте обе языковые версии, узкий экран, клавиатуру, копирование, печать и чтение без JavaScript. Вкладки и раскрываемые блоки работают средствами HTML/CSS; собственный JavaScript не требуется.