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!

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. — Wayne Conrad, Feb 28 '13 at 17:08
Okay, thanks for the confirmation that something isn't working. Already trying to contact someone from Rubydoc for help. — Benjamin R., Feb 28 '13 at 17:56
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. — Wayne Conrad, Mar 01 '13 at 13:20

score 4 · Answer 1 · edited Feb 28 '13 at 03:45

4

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.

edited Feb 28 '13 at 03:45

Stuart M

11,458
6
45
59

answered Feb 28 '13 at 03:20

Wayne Conrad

103,207
26
155
191

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? – Benjamin R. Feb 28 '13 at 03:23
I have added the README.md to the root of my gem (http://www.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? – karatedog Apr 10 '16 at 15:58
@karatedog I don't know. You might consider asking that as a new question. – Wayne Conrad Apr 10 '16 at 17:18

score 3 · Accepted Answer · answered Mar 04 '13 at 02:19

3

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.

answered Mar 04 '13 at 02:19

Benjamin R.

323
2
14

Had the same experience - took a day but then the documentation loaded on rubygems.org no problem! – Shaun Apr 05 '13 at 08:29

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

2 Answers2