Documentation Requirements

[llo...@oreillyauto.com]

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

[Ken Barber]

> 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.

Yeah - repeating yourself is awful. /me has written quite a few puppet
doc headers in my time and this is a pet peave. On this line of
thought - I'd prefer to have it grok the description of the param from
a comment field near the property/param or something (like above?),
this would feel more natural.

ken.

[Nick Fagerlund]

Manually generating module docs is kind of a drag. It'd be cool to have them served dynamically directly from the modulepath, with some kind of simple web app. (I think Nigel has already mentioned this internally, but I wanted to get it out in the public thread too.)

[Giovanni Torres]

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