On Wed, 2008-10-22 at 17:57 -0500, Luke Kanies wrote: > 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.
Do you mean that we should evaluate the resources to get their real name, or that the human doing the documentation will have to make sure his doc is well done that it gives its generic name? > > > > 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. What I meant about erb was to produce a "shell" around the markup content (ie to put the page title, any navigation links...). Are you saying that we should just extract the documentation from the existing comments, store it under the name of the attached node and basta? I was envisionning something more complex, which would produce output ala javadoc (which I find pleasant to use) :-) > > > > 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. So do I, hence why I asked first. My own manifests are really poorly documented (shame on me). If I were documenting my modules, I'd document only the public classes and defines (and more specifically their API if I can say it like that, that is what is controllable from the outside). > > > > 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. You are right. But there are information that is difficult to grab. For instance some of my modules are using puppet variables to define behaviour (ie should we configure snmpd with agentx or not...). Those variables can't be documented without human intervention as there are no puppet language structure to define a module interface (on this subject, that's really something I think puppet is lacking: a kind of parametrized class or module system) > > > > 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. :) I spent a couple of hours to understand the structure of rdoc. I'm now almost sure it will be easier to build the manifest documentation on top of it. Here's why: * rdoc already has a markup language (not the best, but it's there). This might even be overridable. * rdoc already has directives (and some can be useful) * rdoc already has an output system that can output html or other formats * rdoc already has a cross-reference system * you can plug language parsers into rdoc easily from the outside * rdoc is distributed with ruby, hence every puppet site has it * if we want custom output, it is still possible The only thing missing to rdoc from a puppet point of view, is a parser that understands manifests structure. Hopefully puppet has one :-) Then the only thing really missing is a translation layer that walks down the manifest structures, emitting rdoc entities on the fly. I'm all in favor of this way because that will speed up the development of this feature, but if you feel that's not the good way, please let me know. Thanks, -- Brice Figureau <[EMAIL PROTECTED]> --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
