I''m having a bit of trouble figuring out the best way to do my puppetdoc stuff. I hope to have actual tutorial introductory "chapter" type documentation as well as individual module documentation, but it seems like all the examples I can find merely re-state the parameters that puppetdoc already noted. I''m trying to find a good whole-tree example for this, and all the examples I''ve been shown tend to be either a single .pp file and its output (oh boy! One .pp file can become a hideous tangled mess of frames and three-lines-of-text-per-page HTML!) or a vague hand-wave toward "rdoc" and instructions to go read the sourceforge (wow are they still around?) pages on rdoc. I saw someone say that it was good at finding "README" files, but: puppetdoc --all --mode rdoc --modulepath ./modules/ --manifestdir ./manifests/ ...was unable to find ./manifests/README or ./manifests/README.rdoc or any other common combination. I tried using the :include: directive at this point, but it didn''t seem to have the effect I expected. I''m a little confused by http://projects.puppetlabs.com/projects/1/wiki/Puppet_Manifest_Documentation which seems to suggest that my puppetdoc comments need to immediately precede a class. Is that a hard and fast rule? Can I not puppetdoc a node or an individual resource? Can I not create structure in addition to that provided by the manifests themselves? Is this simply the wrong tool for my needs? I was hoping for something a bit more useful than just "generate reams of API printouts for the mandatory documentation binder" software, but I''m getting worried that that''s exactly what this is. I want to build tutorial documentation as well as reference, but there appears to be a very heavy reference bias in the output I''m seeing. I''d greatly appreciate any pointers to example manifest trees that make effective use of puppetdoc! -- "If you carefully examine the intercal package (which was not available for a month despite emails about it being a 404), you will discover that . is in ESR''s PATH." -- Joey Hess -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
Hi, First, I''m sorry to hear you have any issues with puppetdoc (and before you ask yourself why I started like this, I wrote the tool :). On 07/02/11 20:19, Nick Moffitt wrote:> I''m having a bit of trouble figuring out the best way to do my puppetdoc > stuff. I hope to have actual tutorial introductory "chapter" type > documentation as well as individual module documentation, but it seems > like all the examples I can find merely re-state the parameters that > puppetdoc already noted. > > I''m trying to find a good whole-tree example for this, and all the > examples I''ve been shown tend to be either a single .pp file and its > output (oh boy! One .pp file can become a hideous tangled mess of > frames and three-lines-of-text-per-page HTML!) or a vague hand-wave > toward "rdoc" and instructions to go read the sourceforge (wow are they > still around?) pages on rdoc.I would recommend having a look to Lab42 modules on Puppet Forge (or github). Alessandro did an amazing job at commenting properly his modules to work with puppetdoc.> I saw someone say that it was good at finding "README" files, but: > > puppetdoc --all --mode rdoc --modulepath ./modules/ --manifestdir ./manifests/Assuming you have modules in ./modules/ and manifests in ./manifests/, then puppetdoc will generate an html tree in ./doc containing all your nodes, classes and modules (and in your case resources).> ...was unable to find ./manifests/README or ./manifests/README.rdoc or > any other common combination. I tried using the :include: directive at > this point, but it didn''t seem to have the effect I expected.Puppetdoc doesn''t support a global manifests/README file. It is only able to extract documentations from your comments embedded in your actual manifests. It is able, though, to use modules/mymodule/README as the cover for your modules. In any case adding --debug to your command line will show you what puppetdoc parsed and understood. Note that running with --all as you were doing, means that puppetdoc will reference every found resources.> I''m a little confused by > http://projects.puppetlabs.com/projects/1/wiki/Puppet_Manifest_Documentation > which seems to suggest that my puppetdoc comments need to immediately > precede a class. Is that a hard and fast rule?This is a hard rule in the sense that there shouldn''t be a single blank line between the comment and the puppet entity (be it a class, node, resource...). Ex: # My super definition # Use like this: # my_super_definition { "test": } # define my_super_definition() { ... } will work, but if you add a blank line between the comment and the define keyword, puppetdoc will lose the comment.> Can I not puppetdoc a > node or an individual resource? Can I not create structure in addition > to that provided by the manifests themselves?Puppetdoc generates the structure for you by understanding how your classes fit, how your modules are layed out and used.> Is this simply the wrong tool for my needs? I was hoping for something > a bit more useful than just "generate reams of API printouts for the > mandatory documentation binder" software, but I''m getting worried that > that''s exactly what this is. I want to build tutorial documentation as > well as reference, but there appears to be a very heavy reference bias > in the output I''m seeing.Yes, this is a tool to produce the reference manual for your modules. I don''t think any automatic tool can produce the kind of documentation you''re trying to achieve, but if you can prove me wrong (especially in the form of a patch or good suggestions that would be awesome). If you follow the best practice to encapsulate your puppet code in classes and modules, then I think puppetdoc can be a really good tool (and you don''t need the --all parameter in this case). In any case, what is produced is a bunch of html files, which means you can do whatever post-processing you want to them. If you just need to include some static html files on top of this, then nothing prevents you to do so :)> I''d greatly appreciate any pointers to example manifest trees that make > effective use of puppetdoc!Hope that helped, -- Brice Figureau My Blog: http://www.masterzen.fr/ -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
Brice, Thanks for your helpful answers. Brice Figureau:> > I saw someone say that it was good at finding "README" files, but: > > ...was unable to find ./manifests/README or ./manifests/README.rdoc or > > any other common combination. I tried using the :include: directive at > > this point, but it didn''t seem to have the effect I expected. > > Puppetdoc doesn''t support a global manifests/README file. It is only > able to extract documentations from your comments embedded in your > actual manifests. > It is able, though, to use modules/mymodule/README as the cover for > your modules.So is there no way to provide introductory documentation visible from the doc/index.html?> but if you add a blank line between the comment and the define > keyword, puppetdoc will lose the comment.Ah! Thank you, that may be one of my biggest confusions.> > Can I not puppetdoc a node or an individual resource?Above you appear to have documented a define. A define is not a class, and I was worried that only classes were supported. Can I puppetdoc a resource within a class?> I don''t think any automatic tool can produce the kind of documentation > you''re trying to achieve, but if you can prove me wrong (especially in > the form of a patch or good suggestions that would be awesome).My goal is to create complete documentation for the puppet newcomer within my organization. It should all live in the same repository as the manifests and modules, and should include a top-level tutorial document of some sort that can link into the reference material easily. I''m happy with the reams-of-reference-pages structure of the puppetdoc output, so long as I can set up the front page to be a single easy-to-print essay explaining the overall architecture of the layout and interplay between pieces. Currently the front page shows a __site__ class, which appears to be magical. I would like to be able to do something like... I dunno: # :include:README.rdoc class __site__ {} To say "that README.rdoc has all of the documentation that should be shown first, and without need for comment delimiters". I''d prefer a less hacky approach, though.> If you follow the best practice to encapsulate your puppet code in > classes and modules, then I think puppetdoc can be a really good tool > (and you don''t need the --all parameter in this case).One need I have is that I keep a very strict distinction between manifests and modules: my modules are all mechanism and my manifests are all policy. As a result, I need to provide a preamble warning newcomers that they need to keep this structure in future. This needs to be among the first things seen when browsing to the documentation. I don''t want "well it was buried down in some module''s documentation page!" to be used as an excuse.> In any case, what is produced is a bunch of html files, which means you > can do whatever post-processing you want to them. If you just need to > include some static html files on top of this, then nothing prevents you > to do so :)My big concern here is maintainability. If I can keep all the documentation in a standard puppet tool, then I don''t end up having to further document some bag on the side. I''d like for the newcomer to "just type make" or something, and out comes the docs. I''d also like for future maintainers not to have to learn two markup systems just to maintain one set of docs. -- Hey, how come nobody here in the future has a time machine except me? -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
On Tue, 2011-02-08 at 10:16 +0000, Nick Moffitt wrote:> Brice, > > Thanks for your helpful answers. > > Brice Figureau: > > > I saw someone say that it was good at finding "README" files, but: > > > ...was unable to find ./manifests/README or ./manifests/README.rdoc or > > > any other common combination. I tried using the :include: directive at > > > this point, but it didn''t seem to have the effect I expected. > > > > Puppetdoc doesn''t support a global manifests/README file. It is only > > able to extract documentations from your comments embedded in your > > actual manifests. > > It is able, though, to use modules/mymodule/README as the cover for > > your modules. > > So is there no way to provide introductory documentation visible from > the doc/index.html? > > > but if you add a blank line between the comment and the define > > keyword, puppetdoc will lose the comment. > > Ah! Thank you, that may be one of my biggest confusions. > > > > Can I not puppetdoc a node or an individual resource? > > Above you appear to have documented a define. A define is not a class, > and I was worried that only classes were supported. Can I puppetdoc a > resource within a class? > > > I don''t think any automatic tool can produce the kind of documentation > > you''re trying to achieve, but if you can prove me wrong (especially in > > the form of a patch or good suggestions that would be awesome). > > My goal is to create complete documentation for the puppet newcomer > within my organization. It should all live in the same repository as > the manifests and modules, and should include a top-level tutorial > document of some sort that can link into the reference material easily. > > I''m happy with the reams-of-reference-pages structure of the puppetdoc > output, so long as I can set up the front page to be a single > easy-to-print essay explaining the overall architecture of the layout > and interplay between pieces. Currently the front page shows a __site__ > class, which appears to be magical.It''s magical in the sense that it is the "main" class, i.e. the global default namespace. For instance if you define some resources/definitions or variables in site.pp or any other manifests outside of any class, then those entities will be attached to the __site__ class.> I would like to be able to do > something like... I dunno: > > # :include:README.rdoc > class __site__ {} > > To say "that README.rdoc has all of the documentation that should be > shown first, and without need for comment delimiters".I will check to see if :include: works correctly first. If it does, then I think adding this as the first line of manifests/site.pp: # :include:README.rdoc might just be enough. If that doesn''t work, let me know and I''ll try to fix the bug.> I''d prefer a less hacky approach, though.In any case, can you file a redmine ticket?> > If you follow the best practice to encapsulate your puppet code in > > classes and modules, then I think puppetdoc can be a really good tool > > (and you don''t need the --all parameter in this case). > > One need I have is that I keep a very strict distinction between > manifests and modules: my modules are all mechanism and my manifests are > all policy. As a result, I need to provide a preamble warning newcomers > that they need to keep this structure in future. This needs to be among > the first things seen when browsing to the documentation. I don''t want > "well it was buried down in some module''s documentation page!" to be > used as an excuse.I understand.> > In any case, what is produced is a bunch of html files, which means you > > can do whatever post-processing you want to them. If you just need to > > include some static html files on top of this, then nothing prevents you > > to do so :) > > My big concern here is maintainability. If I can keep all the > documentation in a standard puppet tool, then I don''t end up having to > further document some bag on the side. I''d like for the newcomer to > "just type make" or something, and out comes the docs. I''d also like > for future maintainers not to have to learn two markup systems just to > maintain one set of docs.That makes perfect sense. I don''t see any reasons for not fixing the problem on puppetdoc. -- Brice Figureau Follow the latest Puppet Community evolutions on www.planetpuppet.org! -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
Brice Figureau:> I will check to see if :include: works correctly first.I was just able to use it in front of a class: # :include:README.rdoc class readme {} I can then browse to __site__::readme in the rdoc HTML output, and see my long essay.> If it does, then I think adding this as the first line of > manifests/site.pp: > > # :include:README.rdocThis doesn''t appear to work for me. The "Module __site__" page lists the nodes, classes and modules within, but provides no documentation of its own.> might just be enough. If that doesn''t work, let me know and I''ll try > to fix the bug.[...]> In any case, can you file a redmine ticket?Happily. I''ll go do that, now that I have an idea of what we both think is desirable. Many thanks for your patience in this thread! -- Man, I love how everyone is like "In my blog, which is a blog on the Internet, which you all may be interested in visiting, I talked about what I am now saying here." -- George Moffitt -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
Nick Moffitt:> # :include:README.rdoc > class readme {} > > I can then browse to __site__::readme in the rdoc HTML output, and see > my long essay. > > > If it does, then I think adding this as the first line of > > manifests/site.pp: > > > > # :include:README.rdoc > > This doesn''t appear to work for me. The "Module __site__" page lists > the nodes, classes and modules within, but provides no documentation of > its own.For those following along, I worked around this by doing the above example like so: # :include:README.rdoc # :main:__site__::readme class readme {} This satisfies my needs for now. Thanks again for all your help! -- "If, as they say, God spanked the town for being over frisky, why did He burn the churches down and save Hotaling''s whisky?" -- 1906 SF Earthquake rhyme -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.