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+unsubscribe@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/puppet-users?hl=en.