Rdoc is not generated if executed on a custom task.

[rplaurindo]

I wrote a task to create doc of my gem in a project folder that install this gem, just reading the Rakefile. I debugging then finding the problem. The method file of the module Rake::DSL (https://github.com/ruby/rake/blob/v10.4.2/lib/rake/dsl_definition.rb#L82) did not run the lines that are within the block passed as a parameter. When checked this method, i saw he calls another, but none of them has the method yield to return execution to the body block. So one of my solutions was:

"Monkey patches"...

# rake/lib/rake/dsl_definition.rb
module Rake
  module DSL

    private
    def file(*args, &block) # :doc:
      Rake::FileTask.define_task(*args, &block)
      # this line has been added
      yield if block_given?
    end

  end
end

The rdoc method that uses the method file is the define of the class RDoc::Task (https://github.com/rdoc/rdoc/blob/v4.2.0/lib/rdoc/task.rb#L243).

Another problem I found was at the time the darkfish generates files in folders. In the method generate_page the variable out_file (https://github.com/rdoc/rdoc/blob/v4.2.0/lib/rdoc/generator/darkfish.rb#L454) gets a junction of paths: the path root of the app, + path rdoc (set to rdoc_dir) + file.path. The problem is file.path because when we define the files with rdoc_files.include if we put the absolute path, gives problem because what should be joined is only the filename, not all the way. I resolved with the method File.basename Ruby.

class RDoc::Generator::Darkfish

  def generate_page file
    setup

    template_file = @template_dir + 'page.rhtml'

    # this line has been modified
    out_file = @outputdir + File.basename(file.path)
    debug_msg "  working on %s (%s)" % [file.full_name, out_file]
    rel_prefix = @outputdir.relative_path_from out_file.dirname
    search_index_rel_prefix = rel_prefix
    search_index_rel_prefix += @asset_rel_path if @file_output

    # suppress 1.9.3 warning
    current          = current          = file
    asset_rel_prefix = asset_rel_prefix = rel_prefix + @asset_rel_path

    @title = "#{file.page_name} - #{@options.title}"

    debug_msg "  rendering #{out_file}"
    render_template template_file, out_file do |io| binding end
  end

end

Now works. I just run: $ rake my_gem:rdoc

They can fix this?

[zzak]

@rplaurindo Sorry for the late response, I'm not confident the monkey patches help me fully understand the issue.

It would be helpful if you could share the "custom" rake task you used to generate documentation.

Thank you!

[rplaurindo]

@zzak Sure.

# lib/tasks/my_engine_name/rdoc/generate.rake
namespace :my_engine do
  desc "Genereates RDoc at folder rdoc/sentinel."
  task :rdoc => :environment do
    load "#{my_absolute_engine_root_path}/Rakefile"
  end
end

: )

[zzak]

@rplaurindo How are you loading this rake task?

And what's my_absolute_engine_root_path?

[rplaurindo]

@zzak sorry about that. my_absolute_engine_root_path it's just a representation of an absolute path, how "/home/rplaurindo/projects/rails/my_engine". The Rails loads this task of "my_engine/lib/tasks/my_engine/rdoc". Understanding?

[zzak]

No problem! Thank you for explaining.

I'll need a smaller reproduction than a Rails app, but I'm curious if Rails isn't doing something weird to Rake that's causing this bug.

Also wondering what the purpose of putting RDoc in an Engine is? Maybe it would work better as a top-level task

[rplaurindo]

@zzak the purpose is to give the user the opportunity to generate the documentation of engine in your project and to consult, even offline, syntax methods, etc...

I know the "RDoc" has another purpose, but if it generates documentation from the file "Rakefile," why would not generate the file "Rakefile" is loaded with a different scope, such as in a task?

[zzak]

I'm not sure either, sorry it was kind of a random question.

In order to move this forward, we need a smaller reproduction case.

The slow path is we make a Rails Engine and consumer test app for debugging, but if it's possible to reproduce without doing all of that I'd be very happy :)

[rplaurindo]

:+1: :) @zzak you would like to do a little example?