> 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).
Yeah, although the point is more to get the documentation for a specific node rather than a module. There would have to be some way of distinguishing both types of documentation - the documentation of your actual manifest so you remember what's going on versus a compiled documentation of all instances that are compiled for a certain node. I might have random comments in my manifests that explain how the module works and what other classes it's calling, but all you'd want in the build doc is 'Install this package, add this user, etc'. Not sure if it'd be easy tell the difference between the two. > 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? Agreed, I see your point on this one. I more suggested it because it seemed an easy way to get what changes are happening from a base install and to use that as a simple document. > 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. Guess that's where I'll start looking. :) Thanks Luke. sh On Aug 25, 12:14 pm, Luke Kanies <[EMAIL PROTECTED]> wrote: > 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 -~----------~----~----~----~------~----~------~--~---
