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

Open

#1,177 opened on Sep 13, 2024 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language: Ruby
Stars: 930
Forks: 465
Avg merge: 3d 10h
Merged PRs (30d): 27

Description

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

Contributor guide

Open the contributing guide

First steps

Read the whole issue, then the project's contributing guide.
Comment on the issue to say you are picking it up — it saves two people doing the same work.
Fork the repository and make your change on a branch.
Open a pull request that references the issue number.

Research direction

Reproduce the failure with the Rakefile's RDoc::Task.new block and rake rdoc, following the documented RDoc::Task example. Trace how rdoc.main and rdoc.rdoc_files.include handle a missing doc/README.rdoc; done means rake rdoc succeeds without that file while still processing lib/**/*.rb.

Written by the indexing model from the issue text.

Assessment

Tech stack: ruby
Domain: documentation, tooling
Issue type: Bug
Difficulty: 3/5
Estimated time: 1-2 days
Activity status: Stale
Clarity: Mostly clear
Newbie friendliness: 52/100