Use markdown format for docs

[st0012]

I used Rails's rdoc-to-md script for the majority of the conversion, and then manually tweaked a few issues that I found.

2 additional changes:

• rake rdoc task is added to simplify the doc generation command.
• Hide top-level methods like IRB.JobManager from the generated docs.

[adam12]

Out of curiosity, why the switch?

[st0012]

I think markdown has basically become the universal format in writing technical content. For example, we use it to write README and contributing guides all the time.

If we keep writing Ruby docs in another format, it means both the maintainers and the contributors need to learn or maintain this knowledge too, which is a huge cost to pay (for example, it makes me think twice before touching the docs). So without seeing a clear benefit of using the rdoc format, I think we should stop paying this additional cost and make the document easier to contribute to, at least to most devs.

(As a reference, almost 2 years ago Ruby also changed its contributing doc from rdoc to markdown format, among other things (ruby/ruby#5899))

[adam12]

I think markdown has basically become the universal format in writing technical content. For example, we use it to write README and contributing guides all the time.

100% agree.

If we keep writing Ruby docs in another format, it means both the maintainers and the contributors need to learn or maintain this knowledge too, which is a huge cost to pay (for example, it makes me think twice before touching the docs). So without seeing a clear benefit of using the rdoc format, I think we should stop paying this additional cost and make the document easier to contribute to, at least to most devs.

I also agree, 100%.

(As a reference, almost 2 years ago Ruby also changed its contributing doc from rdoc to markdown format, among other things (ruby/ruby#5899))

I remember seeing this PR, but I don't recall seeing that Markdown for source code documentation was also considered/encouraged in ruby/* projects, but I am presuming this is the maintainer's choice.

Not worth getting into in this thread, but Ruby documentation is my least favourite part of Ruby currently, so any type of PR that seems to resolve some pain around using RDoc currently piques my interest.

[hsbt]

I'm +1 to convert this. But I'm not sure what is happened mixing md and rdoc format in ruby/ruby repository.

FYI: I have a plan to extract irb from ruby/ruby repo entirely at https://bugs.ruby-lang.org/issues/20309. After that, irb and reline don't have some of concerns related ruby/ruby repo's limitation.

[st0012]

@hsbt Thanks for the reminder 👍
I tested it in ruby/ruby following the instruction here. And indeed, if we simply do the conversion it'd break Ruby's doc for IRB class. However, adding # :markup: markdown as the first comment (after the string literal frozen one) seems to fix the issue.

[hsbt]

@st0012 I discussed this at DevMeeting 2024-03-14. No one against this proposal if there is no issue to mix rdoc and markdown formats. Go ahead this.

[st0012]

@hsbt Thanks for raising this in the dev meeting 🙌