search

ruby / rdoc

RDoc produces HTML and online documentation for Ruby projects.
https://ruby.github.io/rdoc/
Other
844 stars 439 forks source link

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

Open goalaleo opened 2 months ago

goalaleo commented 2 months ago

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 ```ruby # 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