Expand rdoc-ref targets at the end of ri output

[st0012]

There have been several document refactors in ruby/ruby that extract individual methods/classes' documentation into separate files, like ruby/ruby#6567

Because RI is not capable of rendering those references, RI users are left with dramatically fewer documentation on those methods/classes.

This commit adds a new option --expand-ref (default: true) to expand all the rdoc-ref targets at the end of the output.

Closes #1097

[adam12]

Tested this on a few core/stdlib methods and it worked well! :+1:

[adam12]

One issue that's not directly related but should be worth noting is it fails to work on [#module-JSON-label-Parsing+Options].

I know it doesn't start with rdoc-ref but it appears to be a valid reference at least on the HTML generated site.

(the example is from JSON.parse, by the way).

[zenspider]

Might be valid... but it might need to be changed just to fit this PR. Frankly I don't care as long as ri Array#pack works... But I do agree that xrefs for options NEED to be expanded sooner or later. Getting doco that says **opts and then has a broken xref you can't actually use isn't helping ANYONE.

[eregon]

Would it be possible to expand the references inline like detailed in https://github.com/ruby/rdoc/issues/1097#issuecomment-2517618447 ? That would make ri usable again for such cases and be very similar to what used to be before these extractions. (If not, let's merge this, it's clearly better than current state)

[st0012]

@eregon My understanding is that many of the extracted pages are much longer than the original segments. For example, Array#pack before extraction is much shorter than the extracted packed data page. So expanding links inline does not necessarily "restore" the previous experience. IMO, it will give a much worse experience if users suddenly encountered this expanded content when they scroll through the documentation of Array, for example.

[eregon]

It's a good point. Since I never saw that expanded document with ri I forgot what it looks like. IMO https://docs.ruby-lang.org/en/master/packed_data_rdoc.html is near unusable, no matter where or in what format, because it's so long it's very hard to find the relevant directive, to see the overall structure, or to compare to related directives to find the right one (e.g. hard to compare all the integer directives). I think https://docs.ruby-lang.org/en/3.1/Array.html#method-i-pack is much better, it's a concise table I would think anyone who already used Array#pack once would find more useful than a long explanation for every directive. So maybe we should change Array#pack docs to be like https://docs.ruby-lang.org/en/3.1/Array.html#method-i-pack and maybe also include a link to the Packed Data document?

Or the Packed Data document should have a summary table similar to https://docs.ruby-lang.org/en/3.1/Array.html#method-i-pack at the top, that could be a good compromise I think. Then that document would have both the concise/quickly-useful summary table and the longer explanations if the reader wants more details.

In that context of very long references, I agree, expanding the rdoc-ref at the end is probably better indeed.

[st0012]

@adam12 @zenspider @eregon I've released this feature in RDoc 6.9.0. Can you give it a try to see if there's any issue?

[eregon]

This seems to work nicely, thanks!

[eregon]

Ref: PR to add back the concise table for pack/unpack docs: https://github.com/ruby/ruby/pull/12349