[ruby-core:122184] [Ruby Misc#21350] Bundled gems lack online documentation

Issue #21350 has been reported by osyoyu (Daisuke Aritomo). ---------------------------------------- Misc #21350: Bundled gems lack online documentation https://bugs.ruby-lang.org/issues/21350 * Author: osyoyu (Daisuke Aritomo) * Status: Open ---------------------------------------- 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 `require`able without any special installation, it would be nice to have their documentation on docs.ruby-lang.org (or somewhere online reachable from Google). -- https://bugs.ruby-lang.org/

Issue #21350 has been updated by 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](https://docs.ruby-lang.org/en/master/standard_library_md.html#label-Bundled+...) 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 documentation generation workflows for [IRB](https://github.com/ruby/irb/blob/master/.github/workflows/gh-pages.yml), [Reline](https://github.com/ruby/reline/blob/master/.github/workflows/gh-pages.yml), and [RDoc](https://github.com/ruby/rdoc/blob/master/.github/workflows/gh-pages.yml). 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). ---------------------------------------- Misc #21350: Bundled gems lack online documentation https://bugs.ruby-lang.org/issues/21350#change-113331 * Author: osyoyu (Daisuke Aritomo) * Status: Open ---------------------------------------- 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 `require`able without any special installation, it would be nice to have their documentation on docs.ruby-lang.org (or somewhere online reachable from Google). -- https://bugs.ruby-lang.org/

Issue #21350 has been updated by nobu (Nobuyoshi Nakada). https://github.com/ruby/ruby/pull/13371 ---------------------------------------- Misc #21350: Bundled gems lack online documentation https://bugs.ruby-lang.org/issues/21350#change-113344 * Author: osyoyu (Daisuke Aritomo) * Status: Open ---------------------------------------- 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 `require`able without any special installation, it would be nice to have their documentation on docs.ruby-lang.org (or somewhere online reachable from Google). -- https://bugs.ruby-lang.org/

Issue #21350 has been updated by 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. ---------------------------------------- Misc #21350: Bundled gems lack online documentation https://bugs.ruby-lang.org/issues/21350#change-113345 * Author: osyoyu (Daisuke Aritomo) * Status: Open ---------------------------------------- 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 `require`able without any special installation, it would be nice to have their documentation on docs.ruby-lang.org (or somewhere online reachable from Google). -- https://bugs.ruby-lang.org/

Issue #21350 has been updated by 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. ---------------------------------------- Misc #21350: Bundled gems lack online documentation https://bugs.ruby-lang.org/issues/21350#change-113348 * Author: osyoyu (Daisuke Aritomo) * Status: Open ---------------------------------------- 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 `require`able without any special installation, it would be nice to have their documentation on docs.ruby-lang.org (or somewhere online reachable from Google). -- https://bugs.ruby-lang.org/

Issue #21350 has been updated by st0012 (Stan Lo). There actually are quite a few bundled gems having their own docs now, including [CSV](https://ruby.github.io/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. ---------------------------------------- Misc #21350: Bundled gems lack online documentation https://bugs.ruby-lang.org/issues/21350#change-113350 * Author: osyoyu (Daisuke Aritomo) * Status: Open ---------------------------------------- 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 `require`able without any special installation, it would be nice to have their documentation on docs.ruby-lang.org (or somewhere online reachable from Google). -- https://bugs.ruby-lang.org/

Issue #21350 has been updated by 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". ---------------------------------------- Misc #21350: Bundled gems lack online documentation https://bugs.ruby-lang.org/issues/21350#change-113356 * Author: osyoyu (Daisuke Aritomo) * Status: Open ---------------------------------------- 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 `require`able without any special installation, it would be nice to have their documentation on docs.ruby-lang.org (or somewhere online reachable from Google). -- https://bugs.ruby-lang.org/

Issue #21350 has been updated by hsbt (Hiroshi SHIBATA). Status changed from Open to Closed Assignee set to hsbt (Hiroshi SHIBATA) I have no plan to add the documentation of bundled gems under the docs.r-l.o. I don't want to spend the time for coordinating all bundled gems especially gems outside ruby org of GitHub.
I think they should: 1. have their own documentation 2. AND those should be linked from Ruby's doc
I'm +1 to above Stan's direction. However, that decision depends on the bundled gems maintainer. ---------------------------------------- Misc #21350: Bundled gems lack online documentation https://bugs.ruby-lang.org/issues/21350#change-113583 * Author: osyoyu (Daisuke Aritomo) * Status: Closed * Assignee: hsbt (Hiroshi SHIBATA) ---------------------------------------- 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 `require`able without any special installation, it would be nice to have their documentation on docs.ruby-lang.org (or somewhere online reachable from Google). -- https://bugs.ruby-lang.org/
participants (5)
-
Eregon (Benoit Daloze)
-
hsbt (Hiroshi SHIBATA)
-
nobu (Nobuyoshi Nakada)
-
osyoyu (Daisuke Aritomo)
-
st0012 (Stan Lo)