search

docmeta / rubydoc.info

Next generation rdoc.info site
http://rubydoc.info
MIT License
132 stars 43 forks source link

Missing extra_rdoc_files? #32

Closed thinkerbot closed 13 years ago

thinkerbot commented 13 years ago

I declare files like tutorials, the license, history, etc in the extra_rdoc_files configuration for a gemspec. These files seem to be ignored by YARD and do not show up in rubydoc.info. For example with the linecook gem you can see there are lots of extra files that are not appearing:

This is a problem IMO because rubydoc.info will be considered canonical because it's what rubygems.org links to. As it stands, the link:files links I setup to work with RDoc appear broken, and the actual files aren't available for people to discover in lieu of a working link.

Is there a recommended way of getting supplementary docs to be included or is this a bug?

lsegal commented 13 years ago

Hi,

We don't use extra_rdoc_files, or any gem metadata for that matter, on rubydoc.info. YARD relies on files in the package, specifically, the .yardopts file to get source and extra file globs. Using the .yardopts file is documented in YARD's README file, as well as in our knowledge base on rubydoc.info.

lsegal commented 13 years ago

As a sidenote, those links are unlikely to work even if those files were listed as proper extra files in the project because they rely on a specific URL structure that rubydoc.info, and YARD, do not use. For example, you are linking directly to an "html" file which does not exist in your project. There is no guarantee that YARD will generate this file at the path, or that it will be accessible via tha .html extension (as you see in the link above, we strip .html extensions from all our links).

The recommended way to link to extra files in YARD is to use the {file:path/to/filename Optional Title} syntax; this is documented in the Getting Started Guide. You can add titles to files with file metadata too (also documented later in the guide), so that you don't need to make the filename the title and put spaces in your filenames on disk (not very pretty :)). This link syntax does not depend on a specific location for the generated document, since it only relies on the actual source file location. Perhaps RDoc has a way to link to source files as well, but I don't know of any, and we do not hook into any such methods, so they wouldn't work. If you do know of a way to link to RDoc extra files in a filesystem/output-file agnostic manner, we could implement support for it in YARD.

lsegal commented 13 years ago

Also another note: you can change the link to your own documentation page from rubygems.org's administration page. The rubydoc.info link is simply a "sane default" that they have chosen. It works for most projects, but it does not work for all of them. You're free to self-host your documentation if you have specific needs.

thinkerbot commented 13 years ago

Thanks for your thorough response, it is very helpful. Your last tip is especially appreciated. My mind was going down the road of patches but really hosting my own RDoc is probably the sane thing to do.

FYI - The links I use have always seemed successful when I make the code with RDoc. AFAIK they make relative paths such that it's possible to link to extra files regardless of where the RDoc index resides in a url, but I can't remember offhand if that's exactly what's going on. It's ugly and kind of a pain to manage, but it was the best I could figure out.

lsegal commented 13 years ago

Well, from experience (not looking at code), it looks to me like that the syntax you showed above will simply link relative to the root of the output directory. It will always work in RDoc, because RDoc always puts a "files" directory at the root of the output directory, but your relative linking scheme is very much dependent on the way RDoc structures its files. If it were to start putting extra files in "file", or even just started changing those spaces into underscores when generating html, those links would break. This is why YARD abstracts this and just has you link to the input file relative to your project root, not the output directory. If YARD changes output structure, or if the output structure is changed by a plugin or feature like the YARD server layer, links will still work. I don't think RDoc has anyway to guarantee that.

thinkerbot commented 13 years ago

Hi just wanted to cross reference this issue on rdoc/rdoc that is relevant to the link discussion. @drbrain is proposing an rdoc: scheme.