Транклюзия символов
Напишите вики-ссылку на имя функции, и тело функции отобразится на месте с подсветкой синтаксиса, взятое прямо из исходных файлов. AST-извлечение работает для 40+ языков: Python, Swift, JavaScript, TypeScript, Go, Rust, Java, C, C++, Ruby, Kotlin и других. Измените источник — документ обновится.
# Встраиваем функцию по имени
![[auth.py#validate_token]]Ohai извлекает функцию validate_token из файла auth.py и отображает её с подсветкой синтаксиса. Когда функция изменится, документация обновится автоматически.
Почему это важно
Традиционная документация устаревает. Вы копируете код в markdown, код развивается, и внезапно ваша документация начинает вас обманывать. Транклюзия символов решает эту проблему, делая исходные файлы единственным источником истины.
В отличие от ссылок на номера строк, которые ломаются при каждом рефакторинге, транклюзия символов использует AST-парсинг для поиска кода по его настоящему имени — функций, классов, структур, констант. Переименовывайте файлы, реорганизуйте код, добавляйте новые методы — пока имя символа существует, ваша документация остаётся точной.
Сценарии использования
Документация API
Ссылайтесь на реальные сигнатуры функций, а не на набранные вручную приближения, которые расходятся с кодом.
Записи архитектурных решений
Встраивайте обсуждаемый код прямо в ADR. Примеры остаются актуальными по мере развития кодовой базы.
Руководства по адаптации
Покажите новым разработчикам, как работает аутентификация, с живым кодом, которому они могут доверять.
Ревью кода
Извлекайте конкретные функции в markdown-сводку для асинхронного обсуждения и ревью.
Туториалы
Разбирайте реальные реализации. Читатели могут быть уверены, что примеры кода всегда актуальны.
Runbook-инструкции
Встраивайте точную конфигурацию или скрипт, который нужен операторам во время инцидентов.
Поддерживаемые языки
AST-парсинг Tree-sitter для Python, Swift, JavaScript, TypeScript, Go, Rust, Java, C, C++, Ruby, Kotlin, PHP, Scala, Haskell, OCaml, Lua, Elixir, Bash и других — плюс извлекатели путей для форматов данных: ключи JSON, пути YAML, таблицы TOML, пути plist, XML, CSS, SQL и обычный текст. Всего 40+ форматов.
Готовы попробовать документацию, которая никогда не устареет?
Скачать для Mac