[Rubygems-developers] 0.4.0 bugfix release
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')
> # END NEW GEM SPEC OPTIONS
> 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
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.
More information about the Rubygems-developers