0

I am making a rubygem. RDoc is great for documenting classes methods and fields but I want to have an "overview page" that has a basic architecture synopsis of the module how the classes relate to it etc. It doesn't seem right to have that embedded in code for one thing the interpreter has to parse through it every time it loads the files.

Is it right to include this sort of documentation in a rubygem? If so how does one include such non-code embedded docs in a rubygem?

Also, does installing a rubygem, build a "pre-compiled" cache version used at runtime that makes loading faster so voluminous docs are not an issue? or not?

Cœur
  • 37,241
  • 25
  • 195
  • 267
peterk
  • 5,136
  • 6
  • 33
  • 47
  • For the interpreter, rdoc notations are just comments, and are not parsed (except for `#`, `=begin`, `=end`), and their effect is ignorable. – sawa Mar 03 '16 at 17:43

1 Answers1

0

sometimes hard to search for documentation on a documentation generator :)

But the answer is that you can control the behavior of rdoc and specify extra files to include when building and installing a gem in the gemspec object:

http://guides.rubygems.org/specification-reference/

spec.extra_rdoc_files = ['README', 'doc/user-guide.txt']

spec.rdoc_options << '--title' << 'Rake -- Ruby Make' << '--main' << 'README' << '--line-numbers'

peterk
  • 5,136
  • 6
  • 33
  • 47