Я хотел бы включить информацию о задачах Rake в нашем Rails-приложении. Мы используем YARD для документации, и на данный момент такие страницы, как lib/tasks/development.rake, отображаются по умолчанию как неформатированный текст.Как документировать задачи Rake с помощью YARD?
Я могу сделать их рендерингом как исходный код Ruby, используя # @markup rubyfrom the YARD documentation.
Однако, это просто делает любые комментарии встроенными, даже если они включают директивы Ярд, такие как # @!method foo. Это означает, что the YARD documentation on tagging DSLs не подходит.
Я что-то упустил?
Как я могу получить YARD для распознавания кода и документации в файлах .rake?
N.B. Я был бы доволен решением, которое игнорирует фактический код и просто генерирует копию документации, но источником для копии документации должен быть файл .rake - я не хочу, чтобы документация находилась в отдельном файле .markdown (или что-то еще), поскольку есть слишком много шансов на выход из синхронизации.
Подробнее - команда yard:
Я использую .yardopts файл, содержащий следующее:
--asset graphs 'app/**/*.rb' 'lib/**/*.rb' - README info/*
Чтобы получить ДВОР прочитать задачи Rake я могу добавить 'lib/tasks/*.rake'после в дефис (например, добавить файлы Rake в список файлов YARD), но, как указано выше, это не обрабатывает их правильно.
Согласно предложению Бенджамина ниже, я попытался добавить 'lib/tasks/*.rake'перед тем дефиса (то есть добавить Rake файлов в список обычных файлов Ruby, подлежащую обработке), но это, кажется, не порождает ничего.
Возможно, что YARD генерирует что-то, но не в ожидаемом месте/с ожидаемым именем файла. Я полагаю, что я недостаточно хорошо разбираюсь в том, как работает YARD, чтобы выяснить, есть ли где-то потерянный выход. Конечно, нет ничего подходящего в поиске, который генерирует YARD, а простой find doc | grep rake или find doc | grep basename_of_rake_file ничего не показывает.
Это просто вопрос о том, чтобы Двор распознал файлы '* .rake' как рубин? – ipd
Боюсь, я не слишком много смотрел с тех пор, как спрашивал, но я полагаю, что это так. Однако на самом деле _specifying_, что они являются Ruby с директивой '# @markup ruby', не работает, потому что он _only_ отображает Ruby, т. Е. Больше не обрабатывает комментарии к документации – Leo
@Leo, указывает ли расширение рейка в командной строке? _yardoc * .rake -o out/_? – benjamin