On Oct 23, 2008, at 3:48 AM, Brice Figureau wrote:
>
> On Wed, 2008-10-22 at 17:57 -0500, Luke Kanies wrote:
>>
>>
>> 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?
I just mean that for those resources that don't have static names,
your documentation extraction system needs to have some mechanism for
handling them. I.e., treat resources with static names slightly
differently than resources with variables for names.
You'd also want to pay attention to selectors and case statements, I
guess - most of them rely on static values, so you could make some
assumptions about, say, how a given class behaves on different
platforms based on selectors and case statements.
>>
>> 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) :-)
I'm not familiar with Javadoc, but if you like it, then use it as your
starting point, certainly.
>> 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).
Ok.
>> 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)
Yep. As soon as someone comes up with a clear idea of how to do them...
Really, it's something I've been thinking of for a while, but without
the development bandwidth to create them, there hasn't been any need
to fully design them.
>> 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.
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. 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.
--
Life isn't fair. It's just fairer than death, that's all.
-- William Goldman
---------------------------------------------------------------------
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
-~----------~----~----~----~------~----~------~--~---
