Сборка и проверка документации¶
Из корня checkout выполните:
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.