How do I document Rake tasks with YARD?

Question

I would like to include information on the Rake tasks in our Rails app. We use YARD for documentation, and at the moment pages like lib/tasks/development.rake show up by default as unformatted text.

I can make them render as Ruby source code using the # @markup ruby from the YARD documentation.

However, this just renders any comments inline, even if they include YARD directives like # @!method foo. This means the YARD documentation on tagging DSLs doesn’t seem to be applicable.

Am I missing something?

How can I get YARD to recognise code vs documentation in .rake files?

N.B. I would be happy with a solution that ignores the actual code and just generates documentation copy, but the source for the documentation copy must be the .rake file itself – I do not want documentation to live in a separate .markdown file (or whatever) as there’s too much chance of it getting out of sync.

More info - the yard command:

I am using a .yardopts file containing the following:

--asset graphs 'app/**/*.rb' 'lib/**/*.rb' - README info/* 

To get YARD to read the Rake tasks I can add 'lib/tasks/*.rake' after the hyphen (i.e. add Rake files to the YARD ‘Files’ list), but as noted above this does not process them correctly.

As per Benjamin’s suggestion below, I tried adding 'lib/tasks/*.rake' before the hyphen (i.e. add Rake files to the list of regular Ruby files to be processed), but this doesn’t seem to generate anything at all.

It is possible YARD is generating something but not in the expected location / with the expected filename I suppose, I’m not familiar enough with how YARD works to figure out if there is orphaned output somewhere. There is certainly nothing appropriate coming up in the search that YARD generates, and a simple find doc | grep rake or find doc | grep basename_of_rake_file doesn’t show anything.

Answer 1

From YARD documentation:

In the Getting Started Guide with YARD section under Using YARD to Generate Documentation, check out Documenting Extra Files or Adding Meta-Data to Extra Files. It might help.