On Oct 31, 2008, at 5:40 PM, Brice Figureau wrote: > > Hi, > > As promised a couple of weeks ago, here is my first attempt, just in > time > for a creepy Halloween, to provide an application to generate > documentation > for manifests. > > It is based upon a parser modification that associates comments with > statements, and a RDoc based html output tailored for puppet language. > > An example output generated from David Schmidtt modules[*] is > available here: > http://www.masterzen.fr/puppet/rdoc/index.html
This is *awesome*. Once David goes through and comprehensively comments his whole code base, it'll be even better. :) > > It is to be noted that David Schmidtt modules don't contains RDoc > style > markup comments, so sometimes the generated output can seem strange. > > The development version is hosted on my github repository: > http://github.com/masterzen/puppet/tree/feature%2Finline-doc > > Usage: > % puppetdoc --rdoc --outputdir /tmp/doc /path/to/modules > > The generated output ends up in doc by default or into the provided > outputdir. > At first, the output shows the list of all modules and the list of > all classes. > Once you click on a module link in the All modules, the bottom left > screen shows all > the defined defines and classes of this module and the right frame > shows the module documentation. > If you click on a specific class or define it then shows the > documentation for this > specific class or define. > This mimics a little bit the Javadoc output , which I found really > pleasant to use (way > better than the ruby-doc RDoc output IMHO). > > Note: > * the current version only knows how to parse modules. It can't > parse sole > manifests or manifests that are not under a standard module hierarchy. This is a great start, though. Are you planning on adding these? Just supporting the standard site.pp in the 'manifest' setting would be sufficient. > > * the current version fails if you have ruby plugins (facter or > other) in your > modules. This will be fixed soon I hope. > > * only defines, includes, classes and modules (ie README content) > documentation > are generated for this version. > > * there is no rspec tests coverage for the RDoc integration. I > didn't really think > it was necessary. If really needed, please let me know. This is ok for most of it, but some basic tests might be nice. > > * the RDoc integration files are not in the right place (puppet/ > rdoc). I plan to > move them into (puppet/util/rdoc) to not be in the way of the > important parts of > puppet. If needed we can even externalize those files as they are > only needed > by puppetdoc. > > The very next action will be to provide, based on this an ala > 'perldoc' > feature that knows to parse a manifest and produce directly on the > terminal its documentation. What is unknown at this stage is what > documentation to extract from the manifests in 'perldoc' mode, nor > which formatting to apply (if there is one to provide). > > Please review and comment as usual. Testing would be great also, as > I only generated documentations for my own modules and David > Schmidtt ones. This is great. You should send a note to the user list, so the rest of the community has a chance to test. -- Zeilinger's Fundamental Law: There is no Fundamental Law. --------------------------------------------------------------------- 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 puppet-dev@googlegroups.com 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 -~----------~----~----~----~------~----~------~--~---
