How do I add documentation to my gem that will show up on rubygems.org?

Question

Experimenting with pushing my first gem to rubygems.org, and I'm trying to figure out how to generate online documentation for it. For most gems 'show' page, when I click the 'Documentation' link, I am brought to http://rubydoc.info/gems/gemname/version/frames. Is this something that will happen automagically if I generate the docs in the right place? Do I have to specify something in the gemspec? Thanks!

Unreal

You've got me stumped. I thought it was just supposed to happen. The next step might be whatever mailing list or etc. where rubygems support happens. – Pseudohermaphroditism

Okay, thanks for the confirmation that something isn't working. Already trying to contact someone from Rubydoc for help. – Unreal

When you figure it out, I hope you will add an answer (and give yourself the checkbox). I'm curious to know what the trouble was. – Pseudohermaphroditism

Hey Wayne, see below. Thanks again for your help. – Unreal

Answer 1

Here is the response that I received from someone in the RubyDoc community:

Hi there,

New gems can take up to a day to make it into RubyGems' master gem list. Not much we can do about this one. From then on, it's about an hour for new versions of your gem to be populated into the list (we run a cron job at *:15 to update our copy).

It was a matter of letting enough time elapse.

Unreal

Had the same experience - took a day but then the documentation loaded on rubygems.org no problem! – Zoroastrian

Answer 2

rubydoc.info will automatically generate API docs for your gem. At a minimum, those docs will contain the signature of all classes, modules and methods, as well as the comments you put before each method and class.

If you add yardoc markup to your files, the documentation will get better. Here's a small bit of yardoc markup for a method:

# Validate the value.
# @param long_mailer_id truthy if the mailer ID is long (9 digits).
# @raise ArgumentError if invalid

def validate(long_mailer_id)

yardoc, the documentation engine that rubydoc.info uses, will look for comments in a certain format and format them into spiffy documentation.

You can also add, to the root of your gem, a README.md in Markdown format. This will be formatted and used as the "main page" of your documentation.

Pseudohermaphroditism

Thanks for your response Wayne - when I click on 'Documentation' on rubygems.org, I see Oops, We Couldn't Find That Gem We can't seem to find any versions for the gem sygnal. Are you sure you typed it correctly? Is there something I'm missing? – Unreal

I have added the README.md to the root of my gem (rubydoc.info/gems/beziercurve) but it is not used as main page. I have compared the gempsec files, but haven't find any differences. Also strange, I have a version of 0.8.3 or 0.8.4 (the former should be there, and I just updated it to the latter), but Rubydoc is showing "0.8". What's missing? – Bonze

@Bonze I don't know. You might consider asking that as a new question. – Pseudohermaphroditism