[Rubygems-developers] 0.4.0 bugfix release

Gavin Sinclair gsinclair at soyabean.com.au
Mon May 31 18:21:18 EDT 2004


On Tuesday, June 1, 2004, 1:57:52 AM, Jim wrote:

> Gavin Sinclair wrote:
>> On Tuesday, June 1, 2004, 12:31:15 AM, Jim wrote:
>>>I think we still need the ability to add RDoc files (and possibly 
>>>options) to the gem spec.  Without this, the rake documentation 
>>>generated by the automatic rdoc generation option will be incomplete.  I
>>>don't think this has been added yet.
>> 
>> Agreed.  Can you give an example of how you would like the rake
>> gemspec to look?

> This would be great.  The new options are listed below in the commented
>   BEGIN/END section...

>    spec = Gem::Specification.new do |s|
>      [...]
>      s.has_rdoc = true
>      # BEGIN NEW GEM SPEC OPTIONS ...
>      s.rdoc_options << '--title "Rake -- Ruby Make"'
>      s.rdoc_options << '--line-numbers' << '--inline-source'
>      s.rdoc_files.include('README', 'MIT-LICENSE', 'TODO', 'CHANGES')
>      s.rdoc_files.include('lib/**/*.rb', 'doc/**/*.rdoc')
>      s.rdoc_files.exclude(/\bcontrib\b/)
>      # END NEW GEM SPEC OPTIONS
>      [...]
>    end

> The above kinda assumes that a rakes-style FileList object is used for
> the rdoc_files attribute.  If we don't implement that, I would build the
> file list in Rake (e.g. RDOC_FILES) and then just say:

>     s.rdoc_files = RDOC_FILES.to_a

> in the Gem spec.

> If rdoc_files is not explicitly specified, it should default to whatever
> is included today (i.e. something like 'lib/**/*.rb').

That looks excellent.  And it looks like Rake's RDoc capabilities.
That and FileList now make *two* reasons to look at reusing.  So I
like Chad's thought about including a Rake gem with RubyGems and
installing it if needed.

This would give RubyGems specifications more power and clarity, and
more consistency with a current "best practice".  And RubyGems
wouldn't have to implement or document anything extra.

One problem, though: how to reuse Rake's RDoc generator capabilities
without it specifying tasks.  The Rake implementation is not very
orthogonal: you can't just ask it to do something; you have to make a
task and do it later.  Perhaps Rake could factor this out a little for
reusability purposes.

Disclaimer: this idea could be very shallow and infeasible.  I'm
typing this fast in a few minutes I have spare.  The motivation,
however, is clear: how to get maximum power from a gemspec without
having to overcook its implementation (and therefore documentation).

As to the topic of this sub-branch: I definitely support the nature of
what you have demonstrated.

Cheers,
Gavin



More information about the Rubygems-developers mailing list