While it seem to be a short-term fix to the problem, I believe it won't be ideal in the long term due to how individual bundled gems can configure their documentation differently.

For example, if you search IRB on this branch's generated doc, you'd find many files that you'd not see in IRB's official documentation:

But more importantly, you can't see the comprehensive documentation about IRB like you'd on its official doc.

This is because IRB's RDoc configs aren't properly picked up.

We can improve it by either:

• Make bundled gems include .rdoc_options and .document in the gem package so they're available to RDoc in ruby/ruby. But I'm not sure if RDoc supports locally scoped .rdoc_options even if we do that
• Exclude gems that have similar issues, like rdoc, irb, and reline for now (which I recommend to include in this PR if we decided to ship it)

But neither options is ideal for the long-term IMO.

I don't see this as a blocker, but this change will also increase the duration of make html from ~26s to ~67s

Master

  Files:        744

  Classes:     1071 ( 223 undocumented)
  Modules:      174 (  50 undocumented)
  Constants:    986 ( 409 undocumented)
  Attributes:   958 ( 159 undocumented)
  Methods:    11411 (1385 undocumented)

  Total:      14600 (2226 undocumented)
   84.75% documented

  Elapsed: 26.0s

Branch

  Files:       1826

  Classes:     2427 ( 1137 undocumented)
  Modules:      441 (  221 undocumented)
  Constants:   2109 ( 1090 undocumented)
  Attributes:  2696 ( 1328 undocumented)
  Methods:    20615 ( 6718 undocumented)

  Total:      28288 (10494 undocumented)
   62.90% documented

  Elapsed: 67.3s

Thank you for pointing it out.

A merit to include all docs is ri can show them.

• Make bundled gems include .rdoc_options and .document in the gem package so they're available to RDoc in ruby/ruby. But I'm not sure if RDoc supports locally scoped .rdoc_options even if we do that

Why doesn't IRB gem contain .rdoc_options while it is committed to the repository?

But either options is ideal for the long-term IMO.

"not ideal"?

But either options is ideal for the long-term IMO.

Yeah sorry I mean "neither" 🤦‍♂️

A merit to include all docs is ri can show them.

If this is for ri, then I'm less concerned about it. But since the original issue is about online documentation, I don't think this PR should close it.

Why doesn't IRB gem contain .rdoc_options while it is committed to the repository?

Sure we can do that. But even if it's included, we'd still not account for the options configured through RDoc::Task in the Rakefile for that project. So for some projects the generated doc would still not provide the best experience. We can certainly migrate those options to .rdoc_options tho.

Assuming we still want to make bundled gems' html doc generate nestedly under ruby/ruby's, another problem will be to resolve RDoc options in the nested context. For example, how do we deal with the main_page option in a subdirectory? What scope does it apply to?

Finally, it'll also make it hard for bundled gem maintainers to configure their projects' doc for 2 context at the same time. And to fix the doc shipped to docs.ruby-lang.org, maintainers would need to ship new releases with this approach.

So my opinion is: we can make RDoc support nested level of configuration options, and migrate bundled gems to use .rdoc_options for configurations, so bundled gems' html doc build in ruby/ruby are built as well as on their own.

But I think it will be a significantly more costly option than simply linking to those gems' docs from docs.ruby-lang.org. We should implement some features to make those links more discoverable, but it will be a simpler feature to implement and requires only changes in RDoc and later in ruby/ruby.