My gem's docs are blank?

's Avatar

a

29 Apr, 2012 05:35 AM

http://rubydoc.info/gems/chill/frames are blank, though when installing the gem locally and running gem server, everything works great. What's up?

  1. Support Staff 1 Posted by lsegal on 29 Apr, 2012 05:47 AM

    lsegal's Avatar

    I can't imagine it working locally. The default globs for yard are lib/**/*.rb, ext/**/*.c. You seem to be using "library" for your lib path, and there is no .yardopts present to inform YARD of the correct source path.

  2. 2 Posted by Jenna Fox on 29 Apr, 2012 05:58 AM

    Jenna Fox's Avatar

    I don't use YARD locally, gem server is using RDoc I think. Why doesn't rubydoc.info respect the gemspec? Can you fix it on your end? Adding a secret .yardopts file seems like a poor solution for a site intended to parse and display docs from rubygems.

  3. Support Staff 3 Posted by lsegal on 29 Apr, 2012 06:07 AM

    lsegal's Avatar

    Rubydoc.info uses YARD to display documentation for all projects on the site, including gems (see our knowledge base for more info), so in order to be compatible with the site you need to be compatible with YARD. We can't fix it locally because we download and parse gems on request, so I could manually add a .yardopts but it would get deleted once we clear the cache.

    On a sidenote, there is nothing in your gemspec that says anything about where your source files are located for your doc tool (and we don't support rdoc_options anyway), but if you use the standard Ruby conventions of having "lib" as the source path instead of "library", it should work out of the box (you wouldn't need a .yardopts file), since is this is the standard glob based on the RubyGems convention. You can see the RubyGems guide for proper naming conventions: http://guides.rubygems.org/patterns/#consistent-naming using proper naming conventions makes it much easier for other tools/services to interop with your library.

  4. lsegal closed this discussion on 29 Apr, 2012 06:07 AM.

  5. lsegal re-opened this discussion on 29 Apr, 2012 06:13 AM

  6. Support Staff 4 Posted by lsegal on 29 Apr, 2012 06:13 AM

    lsegal's Avatar

    By the way, one of the reasons we don't parse .gemspec files is because they are Ruby executable files. We don't execute any external Ruby on the site for security reasons, as you can imagine, so we can't support anything inside of a .gemspec file, even if the information was there.

  7. 5 Posted by Jenna Fox on 29 Apr, 2012 06:34 AM

    Jenna Fox's Avatar

    That seems fair. Ruby sandboxing is a pain, and it probably isn't worth your effort trying to execute them in a more secure environment (like say, the emscripted ruby 1.8 interpreter http://repl.it/ support, inside a hardy javascript interpreter). I'll pop in the .yardopts in my next release. Thanks for the advise lsegal. ^_^

  8. Support Staff 6 Posted by lsegal on 29 Apr, 2012 06:38 AM

    lsegal's Avatar

    I would recommend renaming your "library" directory to "lib" before messing with a .yardopts. That's much more appropriate for a Ruby library.

  9. 7 Posted by Jenna Fox on 30 Apr, 2012 02:15 PM

    Jenna Fox's Avatar

    For whatever it's worth, I did some digging and .gem files do not contain a gemspec, however the content of the gemspec is largely preserved in the metadata yaml file included in every gem - that metadata includes a list of the files in the gem.

    I wonder what specifically is the hold up against building docs for the ruby files specified in the gemspec, seeing as the information is already here and requires no execution of third party code. It seems to effectively be the Gem::Specification object, serialised in it's final form. Particularly have a look at the require_paths info - that'd be a sensible default I think, to be building docs from. It defaults to ["lib"], but can be configured to any value.

  10. Support Staff 8 Posted by lsegal on 30 Apr, 2012 07:55 PM

    lsegal's Avatar

    The issue with digging into the .gem yaml metadata is that the internal data structures aren't public APIs or stable between RubyGems releases. Note that the official policy for RubyGems regarding third party libs adding extra metadata is to not use the gemspec file, which is why we rely on a .yardopts file. We could theoretically start digging into the gem file for data for gems on rubydoc.info, but we also github projects and non-gem source paths which don't have such gems, so we still need to parse .yardopts. It makes more sense just to use that file for everything. For example, if you want rubydoc.info to work with your project on github before you release a gem, you would still need the .yardopts file. And most likely you would want to use rubydoc.info to preview your docs before releasing the gem.

    Note also that the require_paths setting of a gemspec file doesn't even necessarily list all sources in your code. require_paths is simply there to tell RubyGems which paths should be put on the load path, but it doesn't mean that's where all your code is-- especially in the case where conventions are already not being followed.

  11. lsegal closed this discussion on 20 Mar, 2013 06:59 PM.

Comments are currently closed for this discussion. You can start a new one.

Keyboard shortcuts

Generic

? Show this help
ESC Blurs the current field

Comment Form

r Focus the comment reply box
^ + ↩ Submit the comment

You can use Command ⌘ instead of Control ^ on Mac