33

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.

Leo
  • 4,217
  • 4
  • 25
  • 41
  • Is this simply a matter of getting Yard to recognize `*.rake` files as ruby? – ipd Jan 21 '16 at 22:46
  • 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 – Leo Jan 22 '16 at 09:18
  • @Leo, does specifying the rake extension on the command line help? _yardoc *.rake -o out/_ ? – benjamin Jan 22 '16 at 12:20
  • ... and maybe using the _AT note_ tag? – benjamin Jan 22 '16 at 12:43
  • @benjamin 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? – Leo Jan 25 '16 at 15:53
  • I’ve added some more details on the YARD options I’m using... – Leo Jan 25 '16 at 16:06

1 Answers1

3

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.

BenJaminSila
  • 593
  • 5
  • 12