Using markdown as default and dropping rdoc format support #1424
Description
The year of Linux on the desktop has finally arrived, and unfortunately it's really difficult to find a good documentation browser that would work with all the gems (and not just ruby/rails). For MacBook users, there is a fantastic Dash app that renders HTML documentation in a webview.
I'm trying to rebuild a modern documentation browser for a terminal with my own project - https://poshtui.com . The idea behind this project is to generate "docsets" for every library. Docset includes Markdown formatted documentation with some additional files.
I have built additional gems to achieve this:
https://github.com/skatkov/yard-markdown
http://github.com/skatkov/rdoc-markdown
The biggest issue I'm having is with RDoc. Unfortunately, it supports only HTML as an output format. And it's close to impossible to work around to reliably retrieve Markdown as output.
We already have a couple of known issues related to markdown generation:
https://github.com/ruby/rdoc/issues?q=is%3Aissue%20state%3Aopen%20markdown%20label%3Amarkup-markdown
It would be nice to fix those, but at this point I'm questioning if we need this conversion of markdown -> rdoc -> markdown. Even if we fix known issues, there are probably other issues that are still unknown.
Markdown has become a standard format for technical documentation, and I have never seen the RDoc format being used in any projects that I worked on.
Other languages, like Go or Python, have no issues with generating markdown documentation and use it as a default format.
I'd like to suggest dropping rdoc format completely and moving to Markdown as the default.