Hi, OK, I made some good progress on the subject, and will publish some patches later this week or on next week-end, to gather comments/reviews and directions to where to head this project.
So far, the system does the following: * it can produce html based on RDoc for a modulepath or a module. It produces exactly the same thing as RDoc for ruby except that it shows defines where the ruby versions shows methods. My ultimate plan would be to change the output to something more puppet oriented, which would also contains more documentated types (resource collections, virtual resources, class included, imports...) * and if rdoc is not an option, it can produce html using markdown (rdiscount in fact) for a module or modulepath. It produces a hierarchy of directories (one per module) containing html files in it (one per class or define). That's not really usefull as there is no cross-reference, nor index. This part is still rough and doesn't bring anything more than the RDoc version (except it doesn't use rdoc:-)). It yet does support documenting only classes and defines. I think I'll release it like that, and from there we'll see how we can refine it and move toward something usefull. On 24/10/08 19:22, Luke Kanies wrote: [snip] > That sounds great. I was just concerned because I consider rdoc and > ri to be so horribly designed, from a user's perspective, that I > assumed it was as bad internally. Yes, it is badly architectured. But I'm just building on top of it, leveraging all the referencing code I didn't want to write. > And it seems stupidly difficult to, > say, dynamically extract documentation from a file. One thing I > *really* want is the ability to get on-demand docs from any file, > printed on stdout. > > I really liked how perldoc could trivially do that, and could produce > man pages to boot. That was on my plan too, but you really don't need to understand the language to produce such output. Perldoc justs parses its own blocks (block starting with = up to another starting =). It then feeds every pod blocks to a formatter than in turns return man, html or whatever. Doing the same for puppet can be down with a couple of ruby lines to just read the comments strip the leading # and format the result. That's the complex part if nroff is needed to display as man pages or on console, although the output can still be processed by something else (like pandoc[1]). If you want something like this, that's easy to have based on the current infrastructure (I mean the doc stuff in the ast). The only drawback is that you have to loose the knowledge of the ast element where the documentation is attached (ie there is no more contextual documenations). The other issue is the output formatter: what markup in the documenation, and what output formatter? Anyway, I'll publish the patch when it'll be a little bit more polished, that will certainly be the start of a new discussion :-) Also something that is irritating is that the parsers fails if the manifests uses a puppet function defined in external ruby code (usually pluginsync'ed). That's the same thing than in --parseonly mode. I don't think that's necessary to fail during parsing. Could this verification be moved into the evaluation part of AST::Function? For the common mortal that parse _and_ compile, that doesn't change anything, or am I wrong? [1]: http://johnmacfarlane.net/pandoc/ -- 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 -~----------~----~----~----~------~----~------~--~---
