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

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

[osyoyu (Daisuke Aritomo) via ruby-core]

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/
 ______________________________________________
 ruby-core mailing list -- ruby-core@ml.ruby-lang.org
 To unsubscribe send an email to ruby-core-leave@ml.ruby-lang.org
 ruby-core info -- https://ml.ruby-lang.org/mailman3/lists/ruby-core.ml.ruby-lang.org/

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

[st0012 (Stan Lo) via ruby-core]

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+gems) 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/
 ______________________________________________
 ruby-core mailing list -- ruby-core@ml.ruby-lang.org
 To unsubscribe send an email to ruby-core-leave@ml.ruby-lang.org
 ruby-core info -- https://ml.ruby-lang.org/mailman3/lists/ruby-core.ml.ruby-lang.org/

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

[nobu (Nobuyoshi Nakada) via ruby-core]

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/
 ______________________________________________
 ruby-core mailing list -- ruby-core@ml.ruby-lang.org
 To unsubscribe send an email to ruby-core-leave@ml.ruby-lang.org
 ruby-core info -- https://ml.ruby-lang.org/mailman3/lists/ruby-core.ml.ruby-lang.org/

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

[Eregon (Benoit Daloze) via ruby-core]

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/
 ______________________________________________
 ruby-core mailing list -- ruby-core@ml.ruby-lang.org
 To unsubscribe send an email to ruby-core-leave@ml.ruby-lang.org
 ruby-core info -- https://ml.ruby-lang.org/mailman3/lists/ruby-core.ml.ruby-lang.org/

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

[Eregon (Benoit Daloze) via ruby-core]

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/
 ______________________________________________
 ruby-core mailing list -- ruby-core@ml.ruby-lang.org
 To unsubscribe send an email to ruby-core-leave@ml.ruby-lang.org
 ruby-core info -- https://ml.ruby-lang.org/mailman3/lists/ruby-core.ml.ruby-lang.org/

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

[st0012 (Stan Lo) via ruby-core]

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/
 ______________________________________________
 ruby-core mailing list -- ruby-core@ml.ruby-lang.org
 To unsubscribe send an email to ruby-core-leave@ml.ruby-lang.org
 ruby-core info -- https://ml.ruby-lang.org/mailman3/lists/ruby-core.ml.ruby-lang.org/

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

[osyoyu (Daisuke Aritomo) via ruby-core]

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/
 ______________________________________________
 ruby-core mailing list -- ruby-core@ml.ruby-lang.org
 To unsubscribe send an email to ruby-core-leave@ml.ruby-lang.org
 ruby-core info -- https://ml.ruby-lang.org/mailman3/lists/ruby-core.ml.ruby-lang.org/

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

[hsbt (Hiroshi SHIBATA) via ruby-core]

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/
______________________________________________
 ruby-core mailing list -- ruby-core@ml.ruby-lang.org
 To unsubscribe send an email to ruby-core-leave@ml.ruby-lang.org
 ruby-core info -- https://ml.ruby-lang.org/mailman3/lists/ruby-core.ml.ruby-lang.org/