Puppet

This is a feature request for which there’s already a solution. Hope you will review and eventually accept it.

PuppetDoc uses the file README in a module to generate the main page of a module’s documentation. If this file is in rdoc format it renders it nicely. At the same time many modules are published on GitHub, where README files are rendered as rdoc if they are named README.rdoc

The request is to make puppetdoc renders files called README.rdoc ad module documentation if they are found on the module, otherwise it falls back to the standard README.

I already asked Brice an help about this and he replied, in very few minutes with this:

Here is a patch that should quite do what you need:

diff --git a/lib/puppet/util/rdoc/parser.rb b/lib/puppet/util/rdoc/parser.rb
index a8996ee..5fa3246 100644
--- a/lib/puppet/util/rdoc/parser.rb
+++ b/lib/puppet/util/rdoc/parser.rb
@@ -129,8 +129,10 @@ class Parser
  def scan_top_level(container)
    # use the module README as documentation for the module
    comment = ""
-    readme = File.join(File.dirname(File.dirname(@input_file_name)), "README")
-    comment = File.open(readme,"r") { |f| f.read } if FileTest.readable?(readme)
+    %w{README README.rdoc}.each do |rfile|
+      readme = File.join(File.dirname(File.dirname(@input_file_name)), rfile)
+      comment = File.open(readme,"r") { |f| f.read } if FileTest.readable?(readme)
+    end
    look_for_directives_in(container, comment) unless comment.empty?

    # infer module name from directory

It is fully untested :) It should prefer a README.rdoc over a README if both are present.

I’ve tested this patch on Puppet 2.7.9 and it seems to work as expected: – modules with a README are rendered well – modules with a README.rdoc are rendered well – modules with both render README.rdoc