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!

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.

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.