Hi there, I''m trying to document my puppet manifests, and I have created kind of a template for class documentation. After documenting a few I thought it would be great for complex manifests if we could have a tool that read some kind of standard documentation in puppet manifests and create HTML (or other format) documentation, as javadoc in Java or RDoc (?) in Ruby. So two questions: are people interested in creating a standard way of documenting manifests? (is so, I could create a wiki page with my initial template). Do you think it''s interesting having such a tool? Best regards Jose _______________________________________________ Puppet-users mailing list Puppet-users@madstop.com https://mail.madstop.com/mailman/listinfo/puppet-users
On Feb 8, 2007, at 9:33 AM, José González Gómez wrote:> Hi there, > > I''m trying to document my puppet manifests, and I have created kind > of a template for class documentation. After documenting a few I > thought it would be great for complex manifests if we could have a > tool that read some kind of standard documentation in puppet > manifests and create HTML (or other format) documentation, as > javadoc in Java or RDoc (?) in Ruby. So two questions: are people > interested in creating a standard way of documenting manifests? (is > so, I could create a wiki page with my initial template). Do you > think it''s interesting having such a tool?I think this would be great. It''d be worth looking at directly associating documentation with resources, too, either using this embedded doc stuff, or by just adding it as a parameter. If we supported documentation parameters for resources, then we could set things up so that the documentation was kept throughout the process, e.g., logging and reporting. It could be that the parser could extract these embedded docs and add them to resources. E.g., if there''s a comment before a resource, automatically add the contents of that comment as the doc string for the resource. That should be pretty straightforward. The one thing I would say about this (I may have already said this) is that we need to pick a documentation markup format that already exists; markdown would be fine. I prefer Restructured Text as a markup, but there''s not yet a ruby parser for it. -- No one who cannot rejoice in the discovery of his own mistakes deserves to be called a scholar. --Donald Foster --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com
2007/2/8, Luke Kanies <luke@madstop.com>:> > On Feb 8, 2007, at 9:33 AM, José González Gómez wrote: > > > Hi there, > > > > I''m trying to document my puppet manifests, and I have created kind > > of a template for class documentation. After documenting a few I > > thought it would be great for complex manifests if we could have a > > tool that read some kind of standard documentation in puppet > > manifests and create HTML (or other format) documentation, as > > javadoc in Java or RDoc (?) in Ruby. So two questions: are people > > interested in creating a standard way of documenting manifests? (is > > so, I could create a wiki page with my initial template). Do you > > think it''s interesting having such a tool? > > I think this would be great.Ok, you may take a look at the first draft at http://www.reductivelabs.com/trac/puppet/wiki/DocumentingManifests It''d be worth looking at directly associating documentation with> resources, too, either using this embedded doc stuff, or by just > adding it as a parameter. If we supported documentation parameters > for resources, then we could set things up so that the documentation > was kept throughout the process, e.g., logging and reporting.I think I prefer embedded doc rather than a parameter. I may be biased, as I''ve been working for years with Java, and javadoc works that way, but I think adding it as a parameter inside the resource definition would make the definition less readable. Also how would you apply this parameter approach to classes or defaults? It could be that the parser could extract these embedded docs and add> them to resources. E.g., if there''s a comment before a resource, > automatically add the contents of that comment as the doc string for > the resource. That should be pretty straightforward.I think this would be great. Best regards Jose _______________________________________________ Puppet-users mailing list Puppet-users@madstop.com https://mail.madstop.com/mailman/listinfo/puppet-users
On Feb 9, 2007, at 3:49 AM, José González Gómez wrote:> > I think I prefer embedded doc rather than a parameter. I may be > biased, as I''ve been working for years with Java, and javadoc works > that way, but I think adding it as a parameter inside the resource > definition would make the definition less readable. Also how would > you apply this parameter approach to classes or defaults?Okay, sounds great. -- The Microsoft Exchange Information Store service depends on the Microsoft Exchange Directory service which failed to start because of the following error: The operation completed successfully. --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com
Didn''t know where would be the prefered way to add to the proces, so posting here: On 2/9/07, José González Gómez <jgonzalez.openinput@gmail.com> wrote:> > Ok, you may take a look at the first draft at > http://www.reductivelabs.com/trac/puppet/wiki/DocumentingManifests >I''d like to propose to use some kind of identifier of the actual documentation. Either using ## in front of each line or use something like ##manifest-doc-start # # ... # ##manifest-doc-finish (Lame example, but just to give you an idea.) This would allow you to add normal documentation within the manifest, without it being mistaken for "documentation-to-HTML" when there''ll be a tool in the future. What do you think? -- Gegroet, Tim _______________________________________________ Puppet-users mailing list Puppet-users@madstop.com https://mail.madstop.com/mailman/listinfo/puppet-users
On Feb 12, 2007, at 9:15 AM, Tim Stoop wrote:> Didn''t know where would be the prefered way to add to the proces, > so posting here: > > On 2/9/07, José González Gómez < jgonzalez.openinput@gmail.com> wrote: > Ok, you may take a look at the first draft at http:// > www.reductivelabs.com/trac/puppet/wiki/DocumentingManifests > > I''d like to propose to use some kind of identifier of the actual > documentation. Either using ## in front of each line or use > something like > > ##manifest-doc-start > # > # ... > # > ##manifest-doc-finish > > (Lame example, but just to give you an idea.) > > This would allow you to add normal documentation within the > manifest, without it being mistaken for "documentation-to-HTML" > when there''ll be a tool in the future. > > What do you think?If we do this, we should (as much as possible) follow others who have trod here before. I think perl, python, and ruby all have pretty standard and pretty simple ways of doing this. -- I have an answering machine in my car. It says, "I''m home now. But leave a message and I''ll call when I''m out. -- Stephen Wright --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com