Warning on README.md files not found during Rails 7.1 gem installation

[mohits]

Steps to reproduce

On WIndows with Ruby 3.2, do gem install rails

Expected behavior

No warnings about README.md files should be found.

Actual behavior

Instead, we get the following items littered through the installation information (some are extracted).

Couldn't find file to include 'README.rdoc' from lib/minitest.rb
Couldn't find file to include 'activesupport/README.rdoc' from lib/active_support.rb
Couldn't find file to include 'actionview/README.rdoc' from lib/action_view.rb
Couldn't find file to include 'activemodel/README.rdoc' from lib/active_model.rb
...
Couldn't find file to include 'actioncable/README.md' from lib/action_cable.rb

System configuration

Rails version: 7.1

Ruby version: ruby 3.2.0 (2022-12-25 revision a528908271) [x64-mingw-ucrt]

[skipkayhil]

Thanks for opening the issue! I was able to reproduce this with just gem install rails

[p8]

It probably happens because of lines like the following: https://github.com/rails/rails/blob/e5124aed3fdcacb05204391e236c4fd60a1e6e74/activesupport/lib/active_support.rb#L35 Introduced in: https://github.com/rails/rails/pull/47717

[takeshi-codes]

I would like to work on this issue. May I have permission to take it on?

[mohits]

@thisisdylandev - I think just go ahead... can't imagine anyone complaining 🙂

[rafaelfranca]

This is interesting. It is also failing for minitest and the include in minitest didn't change for 8 years https://github.com/minitest/minitest/blame/master/lib/minitest.rb#L9

So maybe it is an issue on rdoc?

[zzak]

Ok, I looked into this.

Basically, inside of activesupport/lib/active_support.rb we have :include: activesupport/README.rdoc.

When generating the documentation with rake rdoc from the Rails root, this path is correct. However, when gem install is running rdoc inside of the activesupport bundle so the two paths are conflicting.

I'm not really sure there is a way to fix this.

[p8]

Maybe we should move rendering the README on the index to sdoc instead?

[zzak]

Maybe, I'd have to see what you mean.

I don't like that RG runs rdoc in the first place, we write documentation for api.rubyonrails.org. I expect other things to be broken not being generated using our api task.

[p8]

Maybe we can do something similar to the guides, and show a warning on other docs: https://github.com/rails/rails/blob/633eb5a9f4f7ed9e638ac5b6b9ee04f323bb61c0/guides/source/active_record_basics.md?plain=1#L1

On the other hand I don't think every gem should have their own custom documentation. I'd rather upstream rdoc customizations.

[rafaelfranca]

@p8 @zzak do you want to fix this issue?

[p8]

We could have our own directive that RDoc doesn't recognize, so it would skip it instead. :sdoc_include: activesupport/README.rdoc It would be a subclass of: https://github.com/ruby/rdoc/blob/4e14158255ad8de64041105470d88f66b6e22e98/lib/rdoc/markup/include.rb I'll try to make a PR for SDoc.

[jonathanhefner]

Looking at RDoc's find_include_file, I believe it will resolve paths relative to the current file's directory. Therefore, we should be able to just write :include: ../README.rdoc in e.g. activesupport/lib/active_support.rb

[p8]

Yes, good point @jonathanhefner. I've created https://github.com/rails/rails/pull/50789

[mohits]

Thank you!