rdoc icon indicating copy to clipboard operation
rdoc copied to clipboard

Trying to run `rake rdoc` without pre-existing main file raises an error

Open goalaleo opened this issue 1 year ago • 0 comments

I'm following this documentation on how to add a rake task for generating the documentation. After defining the rake task trying to run rake rdoc raises

rake aborted!
Don't know how to build task 'doc/README.rdoc' (See the list of available tasks with `rake --tasks`)

I figured out that pre-creating the doc/README.rdoc file fixes the error, but to be honest it's not very clear from the docs that this file needs to be manually created first and the error is not very clear.

Suggestion: Automatically create the main file if it doesn't exist yet

My Rakefile
# frozen_string_literal: true

require "bundler/gem_tasks"
require "rspec/core/rake_task"
require "rubocop/rake_task"
require "rdoc/task"

RSpec::Core::RakeTask.new(:spec)
RuboCop::RakeTask.new

RDoc::Task.new do |rdoc|
  rdoc.main = "doc/README.rdoc"
  rdoc.rdoc_files.include("doc/README.rdoc", "lib/**/*.rb")
end

task default: %i[spec rubocop rdoc]
My Gemfile.lock
PATH
  remote: .
  specs:
    code_words (0.1.0)

GEM
  remote: https://rubygems.org/
  specs:
    ast (2.4.2)
    coderay (1.1.3)
    diff-lcs (1.5.1)
    json (2.7.2)
    language_server-protocol (3.17.0.3)
    method_source (1.1.0)
    parallel (1.26.3)
    parser (3.3.5.0)
      ast (~> 2.4.1)
      racc
    pry (0.14.2)
      coderay (~> 1.1)
      method_source (~> 1.0)
    psych (5.1.2)
      stringio
    racc (1.8.1)
    rainbow (3.1.1)
    rake (13.2.1)
    rdoc (6.7.0)
      psych (>= 4.0.0)
    regexp_parser (2.9.2)
    rspec (3.13.0)
      rspec-core (~> 3.13.0)
      rspec-expectations (~> 3.13.0)
      rspec-mocks (~> 3.13.0)
    rspec-core (3.13.1)
      rspec-support (~> 3.13.0)
    rspec-expectations (3.13.3)
      diff-lcs (>= 1.2.0, < 2.0)
      rspec-support (~> 3.13.0)
    rspec-mocks (3.13.1)
      diff-lcs (>= 1.2.0, < 2.0)
      rspec-support (~> 3.13.0)
    rspec-support (3.13.1)
    rubocop (1.66.1)
      json (~> 2.3)
      language_server-protocol (>= 3.17.0)
      parallel (~> 1.10)
      parser (>= 3.3.0.2)
      rainbow (>= 2.2.2, < 4.0)
      regexp_parser (>= 2.4, < 3.0)
      rubocop-ast (>= 1.32.2, < 2.0)
      ruby-progressbar (~> 1.7)
      unicode-display_width (>= 2.4.0, < 3.0)
    rubocop-ast (1.32.3)
      parser (>= 3.3.1.0)
    ruby-progressbar (1.13.0)
    stringio (3.1.1)
    unicode-display_width (2.5.0)

PLATFORMS
  arm64-darwin-23
  ruby

DEPENDENCIES
  code_words!
  pry (~> 0.14)
  rake (~> 13.2)
  rdoc (~> 6.7)
  rspec (~> 3.13)
  rubocop (~> 1.66)

BUNDLED WITH
   2.5.11

Running the rake task without an existing doc/README.rdoc file raises an error.

$ rake rdoc
rake aborted!
Don't know how to build task 'doc/README.rdoc' (See the list of available tasks with `rake --tasks`)
/Users/leokiiski/.rvm/gems/ruby-3.3.0/gems/rake-13.2.1/exe/rake:27:in `<top (required)>'
/Users/leokiiski/.rvm/gems/ruby-3.3.0/bin/ruby_executable_hooks:22:in `eval'
/Users/leokiiski/.rvm/gems/ruby-3.3.0/bin/ruby_executable_hooks:22:in `<main>'
Tasks: TOP => rdoc => html/created.rid
(See full trace by running task with --trace)

After creating the file first it works

$ touch doc/README.rdoc
$ rake rdoc
Parsing sources...
100% [ 4/ 4]  lib/code_words/version.rb

Generating Darkfish format into /Users/leokiiski/personal/code_words/html...

  Files:      4

  Classes:    2 (2 undocumented)
  Modules:    1 (1 undocumented)
  Constants:  1 (1 undocumented)
  Attributes: 0 (0 undocumented)
  Methods:    2 (2 undocumented)

  Total:      6 (6 undocumented)
    0.00% documented

  Elapsed: 0.0s

goalaleo avatar Sep 13 '24 11:09 goalaleo