How's this for a description of how the doc system works: A doc plugin is just a post_install hook.
Because they are hooks, they can not cancel each other out or generally know who is has run or will run next. All possible doc plugins will always be active and decide if they should run based on the value of the "document" variable. - The default doc plugin is triggered from the presence of "rdoc" and "ri" in document If a doc plugin is a meta plugin, thus wishes to delegate to another, it must simply use an API provided by another plugin. - For example, a plugin which wishes to download docs from the internet and generate docs rdoc second would simply call the Gem::RDoc class to do so. A gem which sets metadata['document'], it's contents will replace the document variable. - This allows a gem to override which doc format/tool should be used for it's docs The CLI or .gemrc can prevent a value from being removed from document by a gem by prefixing the value with a + sign. So if a gem sets metadata['document'] = 'evandoc' and on the CLI there is `--document +ri`, then the document variable will contain "ri", and "evandoc" - Evan -- Evan Phoenix // e...@fallingsnow.net On Thursday, June 9, 2011 at 1:06 PM, James Tucker wrote: > > On Jun 9, 2011, at 10:42 AM, Evan Phoenix wrote: > > > See below. > > > > -- > > Evan Phoenix // e...@fallingsnow.net (mailto:e...@fallingsnow.net) > > > > > > On Tuesday, June 7, 2011 at 7:41 PM, Loren Segal wrote: > > > > > Hi Eric, > > > > > > On 6/7/2011 8:23 PM, Eric Hodel wrote: > > > > Additionally the documentation types are available through the > > > > installer instance passed to the done_installing hook: > > > > > > > > Gem.done_installing do |installer, specs| > > > > if installer.document.include? 'pretend' then > > > > puts "Pretending to document: #{specs.map { |spec| spec.full_name }}" > > > > end > > > > end > > > > > > I take it that other documentation tools are expected to build plugins > > > in this fashion that perform the appropriate documentation generation. > > > However, In the case of static generation of HTML, it usually only makes > > > sense to have one tool run-- so is there a way for the plugin to cancel > > > the builtin rdoc hooks from running in this case? If so, what would be > > > the recommended way? If not, can such a method be added? > > The direction currently is focused on the developer having that control > > rather than a gem being able to take control when it's installed. If a user > > would like to use yard, they can set `:document: "yard"` in their .gemrc > > (could be the system one or the user one). We feel like this addresses the > > first concern, namely that users are able to specify yard generate all > > their docs. > > > > The 2nd issue how should a gem indicate "i'd like tool X to generate docs > > for me". This was what has_rdoc did previously. I've committed the ability > > to set metadata, so my plan was to allow a gem to specify a "document" key > > in the metadata would would function the same as the --document CLI option. > > This way, a gem can have control of how it's documentation be generated if > > it wishes. > > > > How do these sound? > > Might it be sensible for that to indicate a document type/style rather than a > tool, and then to infer "a compatible document generator", for future safety? > > > > > > > - Loren > > > _______________________________________________ > > > Rubygems-developers mailing list > > > http://rubyforge.org/projects/rubygems > > > Rubygems-developers@rubyforge.org > > > (mailto:Rubygems-developers@rubyforge.org) > > > http://rubyforge.org/mailman/listinfo/rubygems-developers > > > > > > _______________________________________________ > > Rubygems-developers mailing list > > http://rubyforge.org/projects/rubygems > > Rubygems-developers@rubyforge.org (mailto:Rubygems-developers@rubyforge.org) > > http://rubyforge.org/mailman/listinfo/rubygems-developers > > _______________________________________________ > Rubygems-developers mailing list > http://rubyforge.org/projects/rubygems > Rubygems-developers@rubyforge.org (mailto:Rubygems-developers@rubyforge.org) > http://rubyforge.org/mailman/listinfo/rubygems-developers _______________________________________________ Rubygems-developers mailing list http://rubyforge.org/projects/rubygems Rubygems-developers@rubyforge.org http://rubyforge.org/mailman/listinfo/rubygems-developers
