Документация всегда была важной частью процесса внедрения в нетривиальную систему. По этой причине разработчики упакованного программного обеспечения начали включать файлы README в документацию своих дистрибутивов еще в середине 1970-х годов.

Сегодня readme все еще существует, но превратился в файл README.md, основанный на разметке, который живет в системе контроля версий вашего репозитория. Это стало частью современной культуры разработки, и вы найдете их повсюду.

Ретро-терминал Apple2 от Swordfish90 просматривает README.md от rdme

Снижение входных барьеров для разработчиков

В Stateful мы стремимся снизить барьеры на пути разработчиков и сделать предварительные условия, настройку и рабочие процессы как можно более доступными. Платформы хостинга исходного кода, такие как GitHub, уже подняли README.md в качестве основной точки входа в репозиторий в своем UX, но они все еще расходятся с кодом и документацией, и мы хотим видеть больше.

Запускать команды README прямо из терминала?

В первую очередь из-за раздражения от бесконечного копирования и вставки README, наш коллега Адам Бабик решил использовать парсер Markdown Abstract Syntax Tree для генерации наивного дайджеста фрагментов README и сделать их легко запускаемыми. Это прототип (идите по счастливому пути!), но мы довольны первыми результатами. Здесь показано использование Husky — популярного решения для управления git-хуками:

💡 Для краткости мы пропустили $ rdme run npm-install.

Легкое выполнение примера с husky

Давайте выполним его

Парсинг все еще далек от совершенства, но с наилучшим подбором шаблонов AST в структуру данных пар фрагментов команд, мы часто можем уловить команды и их подразумеваемое описание. Выводимый список старается поддерживать порядок, изначально определенный в README.md. Не стесняйтесь копировать и вставлять следующее пошаговое описание. Хотя это и не нужно, раз уж у вас есть rdme 😎.

Просто перечислите все команды

$ rdme list

Подготовить скрипты package.json для git-pre-commit hook

$ rdme run npm-pkg

Теперь установите пример pre-commit husky hook

$ rdme run npx-husky

Запустите хук pre-commit

$ rdme run git-commit

С помощью простой команды rdme run <name> вы можете запускать блоки команд (проверьте также завершение вкладок) без особых затруднений (как показано выше, при создании образца коммита для запуска git-pre-commit hook). Для простого инструмента CLI мы были приятно удивлены тем, насколько естественным кажется взаимодействие с задачами (если вам нравится терминал). Вы можете найти несколько дополнительных примеров в репозитории rdme.

Возможно, в будущем мы будем использовать автоматизацию для постоянного выполнения команд README и обнаружения устаревших документов, но пока что давайте отлавливать эти проблемы, регулярно запуская их с помощью rdme!

Попробуйте rdme в действии

Если вы работаете на MacOS и используете homebrew, то установить rdme с нашего крана очень просто:

$ brew install stateful/tap/rdme

Вы можете использовать scoop для установки версии rdme на Windows. Однако обратите внимание, что в настоящее время поддерживаются только среды shell (PowerShell пока не поддерживается).

$ scoop bucket add stateful https://github.com/stateful/scoop-bucket.git && scoop install stateful/rdme

Для всех остальных платформ, пожалуйста, ознакомьтесь с разделом установки в README.md программы rdme.

Многое другое, что может rdme

Внутреннее использование rdme привело к длинному списку возможных улучшений, но мы намеренно решили сохранить простоту и выпустить кодовую базу rdme как альфа-версию.

Вот список возможных улучшений:

• более надежный парсинг, настраиваемость и/или ML/AI
• аннотирование разметки для получения детерминированных фрагментов
• введение интерактивности и «цвета» в работу CLI
• встраивание элементов управления запуском и вывода в средство просмотра разметки README
• автоматическое разрешение ENV, внедрение пользовательской конфигурации времени выполнения
• тестируемость C/I, в смысле «всегда знать, когда нарушаешь документацию»
• детерминированный порядок команд, без создания Makefile внутри README
• что еще?

Посмотрите на GitHub вопросы rdme, чтобы лучше понять, какие проекты стоят на повестке дня.

Сообщите нам, как идут дела

Если rdme задел вас за живое или вы испытываете сильные чувства по тому или иному поводу, мы будем рады услышать об этом. Используя этот инструмент, вы наверняка обнаружите нестандартные ситуации. Пожалуйста, не стесняйтесь рассказать нам о них в Discord или просто напишите об этом в комментариях ниже.