On 3/11/08 4:53, Luke Kanies wrote: > 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.
I'm currently working on it, unfortunately I'm stumbling across an issue.: I want the rdoc generator to be independent of any configuration (ie modulepath), so that we can point it at any directory and let it scan. That means that I have to find an heuristic that says, this manifest file is part of a module or this manifest is part of the global 'site' part. My first thought was to check that there is a 'files' and a 'templates' directory in the same path as the manifests dir. For an unknown reason some of my own modules only have the manifests directory, so it seems Puppet doesn't enforce the presence of this dirs. Hence, I can't use this heuristic as is. I can check for a 'modules' directory and infer from that I'm scanning a module, but that seems quite artificial and error-prone. Any idea of a better heuristic, or should I bite the bullet and use the current puppet.conf to check for modulepath? -- Brice Figureau Days of Wonder http://www.daysofwonder.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 -~----------~----~----~----~------~----~------~--~---
