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
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
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.
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.
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 firstname.lastname@example.org.
To unsubscribe from this group, send email to email@example.com.
For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.