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 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. * 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. * 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. [*]: I generated the output from its git repository located here: http://git.black.co.at/ I didn't ask for permission, so I hope this isn't an issue to republish his comments. Brice Figureau (3): Add a doc attribute to AST nodes and fill it with the last seen comments RSpec tests for the doc system (covers AST.doc, lexer and parser) Manifest documentation generation bin/puppetdoc | 135 +++-- lib/puppet/doc.rb | 89 +++ lib/puppet/parser/ast.rb | 2 + lib/puppet/parser/ast/function.rb | 28 +- lib/puppet/parser/grammar.ra | 50 +- lib/puppet/parser/lexer.rb | 42 +- lib/puppet/parser/parser.rb | 256 ++++---- lib/puppet/parser/parser_support.rb | 16 +- lib/puppet/rdoc/generators/puppet_generator.rb | 229 ++++++ .../rdoc/generators/template/puppet/puppet.rb | 791 ++++++++++++++++++++ lib/puppet/rdoc/parser.rb | 208 +++++ spec/unit/parser/ast.rb | 21 + spec/unit/parser/lexer.rb | 37 +- spec/unit/parser/parser.rb | 12 + 14 files changed, 1699 insertions(+), 217 deletions(-) create mode 100644 lib/puppet/doc.rb create mode 100644 lib/puppet/rdoc/generators/puppet_generator.rb create mode 100644 lib/puppet/rdoc/generators/template/puppet/puppet.rb create mode 100644 lib/puppet/rdoc/parser.rb create mode 100644 spec/unit/parser/ast.rb --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
