On Aug 25, 2008, at 11:12 AM, Steve Hajducko wrote: [...] > 1) It's hard to keep docs up to date with configs - you are basically > updating information in two places > 2) Documents are required by audit, even if we don't use them > 3) In certain networks, we *do* need documents, because we don't have > puppetmasters.
I completely agree that autogenerated docs from Puppet code and catalogs are a great idea. > > Any idea how easy this would be to do? I had two thoughts on it and > I've been trying to go through the code, but to a relatively newcomer > to Ruby, it's not the easiest project. :) The best I've come up with, and I think it's pretty decent, is to modify the parser to associate comments with the proceeding syntactical structures. This would be a pretty simple process -- every AST instance would have a 'doc' attribute, and the parser would just cache the most recent comment, and then associate that comment with the next structure, be it a class, resource, or whatever. These docs would then last through the lifetime of the resources and classes -- you'd see them on the client in the catalog, and it should be straightforward indeed to write a simple script that extracts those docs and presents them in some useful way. You could also do auto-extracted documentation from the source code itself then -- parse all of the code, and then do some kind of walking the AST tree to get any instances with docs, and then provide the results in a single document (or, more likely, a per-module document). Neither of these is what I would call hard, but then, I enjoy mucking with parsers. > > Thought 1 > Modify the 'noop' feature to be able to run on a fake node and assume > that every part of the manifest for that node must be applied. This > would net you the result of all changes that must be made to a host > and you could just include it in a document. This is true for any changes that haven't been done, but not otherwise. And you lose intent -- why are the resources on that host in the first place? > > Thought 2 > Modify the providers to include a 'doc' attribute and an option to > print out the documentation for a certain node. Generate the manifest > and print out the doc attributes. This could probably even go into > the type, rather than the provider, depending on how detailed the > documentation needs to be - do you need 'useradd -u 551 shajducko' or > do you just need 'Add user shajducko'? This is a reasonable option, too, and would be very easy -- just have a 'doc' metaparam, and write a simple report that extracts it all. I can see starting with this, and then hopefully moving to auto- extracted docs at some point in the future. -- Always behave like a duck - keep calm and unruffled on the surface but paddle like the devil underneath. -- Jacob Braude --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Developers" 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-dev?hl=en -~----------~----~----~----~------~----~------~--~---
