How does one specify an extra rdoc file

[byrnejb]

I have forked a gem that uses Jeweler to create the gemspec. I have
added rdoc text to one of the library files. When i generate the
rdocs using the rake task directly then I see a link to that library
file which allows me to see the added documentation.

However, I cannot seem to discover what I have to do to the Rake build
task to get this file listed on the front page of the jeweler
generated rdoc. The library documentation is created but no link to
it is provided on the gem index page.

The .document file has the library file explicitly set.

The rake rdoc task also has the library explicitly included.

If I browse to the index page in the rdoc directory in the project
root then I obtain links to the library files. When I go to the doc
directory in the gems then the Darklight generated index.html links
only the LICENSE and the README files . I presume that Darkfish is
called by Jeweler because I cannot find any referencer to it in the
Rakefile of the gem that I am working on.

So, how do I get a link to a library file added to the files list?

[Josh Nichols]

In general, jeweler doesn't really concern itself with rdoc much, except maybe to call the rdoc task at some point. I'm not positive of the specifics off hand, but usually, you have a README type file, and that's the default page when you look at the generated documentation. It might be possible to change this, but I'll have to look into it.

Also, what project is this on? If you can let me know, I can take look and give you a better idea.

- Josh

[byrnejb]

On Jun 3, 10:55 am, Josh Nichols <j...@technicalpickles.com> wrote:
> In general, jeweler doesn't really concern itself with rdoc much, except
> maybe to call the rdoc task at some point. I'm not positive of the specifics
> off hand, but usually, you have a README type file, and that's the default
> page when you look at the generated documentation. It might be possible to
> change this, but I'll have to look into it.
>
> Also, what project is this on? If you can let me know, I can take look and
> give you a better idea.
>

The specific project that I am having this difficulty with is my fork
of Aslak Hellesoy's Cucumber CLI extension called Aruba. The latest
check-in is at: http://github.com/byrnejb/aruba.git.

I am not looking to change the default index page but add links to the
documentation of the included library files. In the old-style rdoc one
was given a frame in which links to source files were provided. If
those files had rdoc comments then following the link would show those
comments.

What is happening with the jeweler setup I have inherited is that
while the rdoc file for the source file is produced when the gem is
created, no link to that file is added to the index page. So the
documentation for that file, although present, remains invisible to
the user.

This may be caused by the lack of any class, module or definition
statements in the referenced files. I do not know enough to tell is
this is an issue or not. However, the basic behaviour of rdoc
evidently does not care so some other factor must be at work.

[Josh Nichols]

On Fri, Jun 4, 2010 at 9:28 AM, byrnejb <byr...@harte-lyne.ca> wrote:

The specific project that I am having this difficulty with is my fork
of Aslak Hellesoy's Cucumber CLI extension called Aruba.  The latest
check-in is at: http://github.com/byrnejb/aruba.git.

I am not looking to change the default index page but add links to the
documentation of the included library files. In the old-style rdoc one
was given a frame in which links to source files were provided.  If
those files had rdoc comments then following the link would show those
comments.

What is happening with the jeweler setup I have inherited is that
while the rdoc file for the source file is produced when the gem is
created, no link to that file is added to the index page.  So the
documentation for that file, although present, remains invisible to
the user.

This may be caused by the lack of any class, module or definition
statements in the referenced files.  I do not know enough to tell is
this is an issue or not.  However, the basic behaviour of rdoc
evidently does not care so some other factor must be at work.

Are you trying to get this to work for when gem install builds rdoc, or when you use `rake doc`? Also, what file are you trying to add now? Is it a .rb file in lib, or something else?

For having it be in the gem-generated rdoc, all the .rb files in lib/ should already be included. On the Jeweler::Tasks declaration (ie the Gem::Specification), you can use `extra_rdoc_files` to add more files that aren't included. This would be at: http://github.com/byrnejb/aruba/blob/master/Rakefile#L7-17

For using the rdoc rake task, I'd suggest taking a look at RDocTask's documentation: http://rake.rubyforge.org/classes/Rake/RDocTask.html ... basically, it'll process anything you specify in `rdoc_files`. Your current setup only has README and lib/, seen here: http://github.com/byrnejb/aruba/blob/master/Rakefile#L46-47

Hope that helps,

- Josh

[byrnejb]

On Jun 4, 11:00 am, Josh Nichols <j...@technicalpickles.com> wrote:

>
> Are you trying to get this to work for when gem install builds rdoc, or when
> you use `rake doc`? Also, what file are you trying to add now? Is it a .rb
> file in lib, or something else?
>

I am trying to get the link to the library file /lib/aruba/
cucumber_steps.rb included somewhere on the index page.

> For having it be in the gem-generated rdoc, all the .rb files in lib/ should
> already be included. On the Jeweler::Tasks declaration (ie the
> Gem::Specification), you can use `extra_rdoc_files` to add more files that
> aren't included. This would be at:http://github.com/byrnejb/aruba/blob/master/Rakefile#L7-17

I have already tried that and I do not seem to change the resulting
index page.

Here is what I have in the Rakefile

<pre>
. . .
begin
require 'jeweler'
Jeweler::Tasks.new do |gem|
gem.version = "0.1.9.jbb.20100601"
gem.name = "aruba"
gem.summary = %Q{CLI Steps for Cucumber}
gem.description = %Q{CLI Steps for Cucumber, hand-crafted for you
in Aruba}
gem.email = "cu...@googlegroups.com"
gem.homepage = "http://github.com/aslakhellesoy/aruba"
gem.authors = ["Aslak Hellesøy", "David Chelimsky"]
gem.add_development_dependency "rspec", ">= 1.3.0"
gem.add_development_dependency "cucumber", ">= 0.7.0.beta.6"
gem.extra_rdoc_files
end
. . .
require 'rake/rdoctask'
Rake::RDocTask.new do |rdoc|
version = File.exist?('VERSION') ? File.read('VERSION') : ""

rdoc.rdoc_dir = 'rdoc'
rdoc.title = "aruba #{version}"
rdoc.rdoc_files.include('README*')
rdoc.rdoc_files.include('lib/aruba/cucumber_steps.rb')
rdoc.rdoc_files.include('lib/**/*.rb')
end
</pre>
and here is the resulting index.html page when the gem is installed:

Files

* LICENSE
* README.rdoc

Classes/Modules

* Aruba
* Aruba::Api

Methods

>
> For using the rdoc rake task, I'd suggest taking a look at RDocTask's
> documentation:http://rake.rubyforge.org/classes/Rake/RDocTask.html...
> basically, it'll process anything you specify in `rdoc_files`.

The rake rdoc task builds a framed index page that contains links to
the files that I wish to include in the gem. It is only when I build
the gem that the links disappear. The documentation files are there,
there is simply no link to them.

[byrnejb]

On Jun 4, 3:07 pm, byrnejb <byrn...@harte-lyne.ca> wrote:

>
> The rake rdoc task builds a framed index page that contains links to
> the files that I wish to include in the gem.  It is only when I build
> the gem that the links disappear.  The documentation files are there,
> there is simply no link to them.

Does anyone have any ideas on how to address this?