You rock dude. -Blake
On Oct 26, 2008, at 12:40 PM, Brice Figureau wrote: > > 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 -~----------~----~----~----~------~----~------~--~---
