On Oct 22, 2008, at 1:26 PM, Brice Figureau wrote: > > Hi, > > On 21/10/08 17:13, Luke Kanies wrote: >> On Oct 21, 2008, at 3:35 AM, Brice Figureau wrote: >> >>> I'm volunteering for this. I'll assign the ticket to myself, if >>> nobody >>> else wants it. >>> [snipped] >>> >>> I'll keep the list posted with my progress and findings. >> >> >> Awesome. > > I've started working on this. I'm following Luke's detailed advice in > the ticket (ie accumulate comment content, attach it on ast nodes when > they're found...). > > That's the easy part... > > Now, imagine that part is working, I'm parsing a manifest, or a module > (or a bunch of modules), how would you structure the results? > > I don't talk about the text formatting (I don't care for the moment), > but more what is pertinent to output in terms of language structures, > and how to structure them. > > I was thinking about the following: > * one output directory for the whole documentation result > * then one directory per modules if any > * in each module directory, one file per puppet class or define from > this module
This sounds good, and straightforward. > > * then we could have a cross reference that would link "entities" > together (ala javadoc or rdoc). > * in each of these files, we should have: > + the comment attached to the AST node of the class/define as > header. > + then each language type (starting with define, variables > assignments, then resource, collection, and override) that has > accompanying documentation, grouped by type. Is it even necessary to > go > that deep? I can't see that variables are necessary to produce in the documentation, but I'd think at least resources, possibly overrides, and probably collections would be a good idea. Resources might be somewhat complicated, because they'll often have variables for names, but the docs will just have to deal with that. > > Does it make sense? > > Now for the formatted output, I could use a bunch of erb to produce > html > (the output formatter will be OO, so I guess you can scrap the default > one and code one that outputs to any format) from any input formatting > (Luke mentioned Markdown since no ReST parser/formatter exists for > ruby). I wouldn't think you'd need erb at all -- just extract the text, treating it as markup, and use the builtin translators to translate it directly to html. > > The next question is should we impose a formalism in the > documentation, > like javadoc is doing by using directives (@ prefixed) to instruct > javadoc about documentation metadata (ie parameters, variables, > definitions...). > This helps format the output documentation and to impose a rigid > structure of the documentation (ie all define will have the same > documentation structure). > If this is needed, then I'd like to start a brainstorming about what > directives would be needed. > On the other hand, having a complete free-form syntax (but user > formatted) is simpler to code :-) I'd go low-structure to start. We can formalize what people "should" do once we've made a bunch of mistakes, then we can import that formalism into the code. At least, I'm not in a good position to assess what makes sense for these directives, so I'd feel better starting with low overhead. > > And finally, I found the following wiki pages that are quite > interesting > (especially the NaturalDocs one): > http://reductivelabs.com/trac/puppet/wiki/DocumentingManifests > http://reductivelabs.com/trac/puppet/wiki/ModuleDocumentationStandards > > I'm wondering if the NaturalDocs approach would not be enough in > itself? > I can already see the objections :-) I think the NaturalDocs is better than nothing, but we've already got a parser that understands the structure of the language, and it seems silly to just ignore that and require people to rebuild that structure in their docs. > > I'll explore the rdoc way soon. I'm pretty sure we can build something > on top of rdoc, but I have to find where is the documenation. Good luck with that. :) -- Whenever I hear anyone arguing for slavery, I feel a strong impulse to see it tried on him personally. -- Abraham Lincoln --------------------------------------------------------------------- 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 [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 -~----------~----~----~----~------~----~------~--~---
