Lee, You have some good points. The Rdoc to html conversion is nice. You can put it on an internal webserver and share with other members of your team. It is a bit tedious, however, and scraping the params from the classes would be a great feature.
NIST provides guidelines for RHEL, along with many other operating systems and applications. I was very excited to see that they are distributing puppet modules in conjunction with the typical, unwieldy spreadsheet to demonstrate the changes! ( http://usgcb.nist.gov/usgcb/rhel/download_rhel5.html) Puppet is touted as self-documenting, but what happens when we want to print out the documentation or incorporate into our existing documentation formats? I use Sphinx for documentation which is based on the fairly simple RST format. I'm sure people out there use a variety of documentation applications to wrangle all their IT docs in one central place. I often update my documentation and periodically print it out and create a binder for reference. I would love to be able to append my puppet modules to this binder. This would make my documentation whole! Before I drift, it seems there are different ideas within the doc module. Here are a few of my thoughts as to how puppet-doc could be useful to me and others similarly (hopefully): * Semi-automated rdoc markup generation would be nice. * An option to output documentation in multiple formats, such as (rdoc, rst, pdf, html, etc.) * An option to convert everything under a single module/ directory directly to output format of choice * An option to convert all documentation under /etc/puppet to output of choice I'm sure others have some other cools ways of how they can use this module. Please contribute your ideas and help shape this useful feature. Giovanni On Friday, July 20, 2012 5:43:01 PM UTC-4, llo...@oreillyauto.com wrote: > > Starting this thread to discuss changes to puppet doc as was recommended > in a different thread. > > Once I finally got the rdoc documentation generation working, I rather > like it. Especially when paired with The Foreman. > > It would be nice if the help was clearer, and it was easier to find a list > of the gems/tools that are required to be able to use it. Or better yet, if > they were included when you installed the puppet package. > > Being able to generate PDF files would be very helpful, as they are easy > to print, and also easy to move around or have as a reference on a mobile > device (such as phone or personal laptop) that may not have network access > to the puppet master. > > As far as the rdoc thing, it's fine with me, but it would be nice if there > was a way to scrape params from the classes w/o having to list out each in > the comments, which I think is part of the actual Ruby rdoc functionality. > > - Lee > -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To view this discussion on the web visit https://groups.google.com/d/msg/puppet-users/-/bZRAsobu0kgJ. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
