Misc #21350: Bundled gems lack online documentation

• Status: Open
• Assignee: -

[osyoyu (Daisuke Aritomo)]

Libraries which have been converted into bundled gems seem to have no online documentation.

For example, csv had its documentation inside docs.ruby-lang.org up to Ruby 3.3:
https://docs.ruby-lang.org/en/3.3/CSV.html

but after it has turned into a bundled gem, there is no online documentation (try searching in https://docs.ruby-lang.org/en/3.4/).

This is the case for all bundled gems, including major modules such as Base64 (missing since 3.4 docs) and Logger (missing since master docs).
Given that these libraries are still requireable without any special installation, it would be nice to have their documentation on docs.ruby-lang.org (or somewhere online reachable from Google).

[st0012 (Stan Lo)]

Yeah it's a problem that we should resolve it before Ruby 3.5's release.

However, if the gem's source is no longer synced to ruby/ruby, then with the current RDoc features it's very hard to generate its documentation as part of Ruby's. Also, if the intention is for those gems to be declared as dependencies, regardless if they can be directly required or not, I think they should:

1. have their own documentation
2. AND those should be linked from Ruby's doc

For 2, we can use the standard libraries page to host those doc. It currently only links to the gems' GH repos, but we can add links to their docs when they have one.

For 1, I have configured/maintained documentation generation workflows for IRB, Reline, and RDoc. As you can see, they are pretty similar. So if we standardize the RDoc generation configs for other bundled gems, we can definitely make a shared GH actions to publish their docs in the same way.

But in addition to code changes, we'll also need to configure each repo to use GH pages. Should be a one time thing but it needs to be done by someone having admin permission to those repos (which I don't have).

[nobu (Nobuyoshi Nakada)]

https://github.com/ruby/ruby/pull/13371

[Eregon (Benoit Daloze)]

I agree each bundled gem hosting its own docs is the best.
In some cases it might be valuable to host multiple versions of the docs, although that quickly adds complexity.

In fact the same applies for normal gems as well.
For example concurrent-ruby hosts its docs at https://ruby-concurrency.github.io/concurrent-ruby/
And FFI should host its docs itself too, especially since the issues with rubydoc.info mentioned in https://github.com/ffi/ffi/pull/1142.

So if we standardize the RDoc generation configs for other bundled gems, we can definitely make a shared GH actions to publish their docs in the same way.

That could be quite convenient, especially if it can be used for normal gems outside the ruby org as well.
https://github.com/ruby/irb/blob/master/.github/workflows/gh-pages.yml is already quite short though so maybe it's good enough as-is.

[Eregon (Benoit Daloze)]

In the meanwhile https://www.rubydoc.info/ is a good workaround to get online docs of all gems, e.g. https://www.rubydoc.info/gems/csv
Though it doesn't handle RDoc includes yet it seems.

[st0012 (Stan Lo)]

There actually are quite a few bundled gems having their own docs now, including CSV.

I've opened a PR to add them: https://github.com/ruby/ruby/pull/13374

I think we're already heading towards this direction albeit slowly. But now we need to think about how to surface these links better in the language doc, like having a way to list them in the search result.

[osyoyu (Daisuke Aritomo)]

I also don't think the documentation for bundled gems necessarily has to be included in the Ruby core documentation, as long it is easily accessible from it.

If possible, how about creating a link-to-documentation-only entry for classes provided by bundled gems (like CSV) ?
That way, users could search for csv in the sidebar and find a pointer.

Perhaps uploading the generated HTML to some place under docs.ruby-lang.org, say docs.ruby-lang.org/gems/csv could make it look more "official".