Issue #11990 has been reported by Alessandro Franceschi.
----------------------------------------
Feature #11990: PuppetDoc should use also README.rdoc files
https://projects.puppetlabs.com/issues/11990
Author: Alessandro Franceschi
Status: Unreviewed
Priority: Normal
Assignee:
Category:
Target version:
Affected Puppet version:
Keywords: puppetdoc
Branch:
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
--
You have received this notification because you have either subscribed to it,
or are involved in it.
To change your notification preferences, please click here:
http://projects.puppetlabs.com/my/account
--
You received this message because you are subscribed to the Google Groups
"Puppet Bugs" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/puppet-bugs?hl=en.
