Documentation for the API?
telemachus opened this issue · 8 comments
Hi,
This is related to #82 (which I think was closed to fast).
The README links to this rdoc page, but if you follow that link, you are greeted with an empty page:
If you try to follow one of the links under Method List, then boom:
As a result, there is no current documentation for the API that I can find. If there's something in particular that needs to be done to get the docs up-to-date, please let me know. I would be happy to help.
Thanks for reporting. Will fix the rdoc.
In the meantime, the README at the bottom gives an example of the only API calls, RDiscount.new and to_html. Although I'll grant that it doesn't indicate the available accessors that turn on other useful features, such as footnote support and similar.
First, I appreciate everything you're doing to bring RDiscount up-to-date. As you say, I really meant the available options and how to set/unset them. (I was just trying to explain this to someone and ended up having to comb through the tests/code which is obviously less easy.)
RDiscount's Rakefile appears to be using hanna to generate RDoc documentation.
However hanna does not install cleanly and hasn't been committed to since 2 years ago, so we should probably migrate to a different doc generator. Thankfully it installs well enough on Ruby 1.9.3 to be usable.
And it appears that the RDoc page being hosted at rdoc.info is using YARD, another doc generation tool.
So, two questions:
- Are you thinking of moving over to YARD?
- Would you like help with that?
I won't have a lot of time immediately, but I would be willing to help in the next couple of weeks, if you want to do it.
PS - I bet that the rdoc.info site would also accept vanilla RDoc documentation as well. That might be an easier switch.
(1) Are you thinking of moving over to YARD?
Perhaps. Right now I'm just trying to determine what tools are currently being used by RDiscount and what tools are available. Based on popularity statistics, it seems that the community votes for vanilla RDoc as a first choice and YARD as a second choice.
I haven't personally used RDoc, YARD, or hanna before, so I have no personal opinion at the moment.
(2) Would you like help with that?
Right now I think the minimum bar is figuring out why the page on rdoc.info isn't rendering correctly. If this turns out to be a complex endeavor, I might take you up on an offer for help. Always appreciated.
In summary, I need to do some more investigation on my end to figure out what needs to be done. If there ends up being a lot of work, I'll circle back with you.
Fixed on HEAD.
The docs are available at: http://rdoc.info/github/rtomayko/rdiscount/master/index
Closing as Fixed.