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+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
