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.

Hols

Is this simply a matter of getting Yard to recognize *.rake files as ruby? – Mulct

I’m afraid I haven’t looked at this much since asking, but I suppose essentially it is, yes. However, actually specifying that they are Ruby with the # @markup ruby directive doesn’t work because it only renders the Ruby, i.e. it no longer processes documentation comments – Hols

@Leo, does specifying the rake extension on the command line help? yardoc *.rake -o out/ ? – Mahound

... and maybe using the AT note tag? – Mahound

@Mahound just tried these, and I’m afraid they don’t seem to work. It works adding lib/tasks/*.rake to the files section of the yardoc command, but then it only reads them as text (as per the question). Adding them to the body of the command doesn’t seem to generate anything for those files at all, i.e. nothing is listed in the Yard class/method/file lists, and there doesn’t seem to be anything in the output doc/ directory. Anywhere else I should look for output? – Hols

I’ve added some more details on the YARD options I’m using... – Hols

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.

Phipps