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
* 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?
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).
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 :-)
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'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.
Comments are welcome as usual...
--
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
-~----------~----~----~----~------~----~------~--~---
