Транклюзия символов
Встраивайте живой код в документацию по имени, а не по номеру строки. Измените исходный код — документация обновится автоматически.
# Встраиваем функцию по имени
![[auth.py#validate_token]]Ohai извлекает функцию validate_token из файла auth.py и отображает её с подсветкой синтаксиса. Когда функция изменится, документация обновится автоматически.
Почему это важно
Традиционная документация устаревает. Вы копируете код в markdown, код развивается, и внезапно ваша документация начинает вас обманывать. Транклюзия символов решает эту проблему, делая исходные файлы единственным источником истины.
В отличие от ссылок на номера строк, которые ломаются при каждом рефакторинге, транклюзия символов использует AST-парсинг для поиска кода по его настоящему имени — функций, классов, структур, констант. Переименовывайте файлы, реорганизуйте код, добавляйте новые методы — пока имя символа существует, ваша документация остаётся точной.
Сценарии использования
Документация API
Ссылайтесь на реальные сигнатуры функций, а не на набранные вручную приближения, которые расходятся с кодом.
Записи архитектурных решений
Встраивайте обсуждаемый код прямо в ADR. Примеры остаются актуальными по мере развития кодовой базы.
Руководства по адаптации
Покажите новым разработчикам, как работает аутентификация, с живым кодом, которому они могут доверять.
Ревью кода
Извлекайте конкретные функции в markdown-сводку для асинхронного обсуждения и ревью.
Туториалы
Разбирайте реальные реализации. Читатели могут быть уверены, что примеры кода всегда актуальны.
Runbook-инструкции
Встраивайте точную конфигурацию или скрипт, который нужен операторам во время инцидентов.
Поддерживаемые языки
Более 30 языков через AST-парсинг Tree-sitter. Даже ключи JSON, пути YAML и таблицы TOML.
Готовы попробовать документацию, которая никогда не устареет?
Скачать для Mac