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 [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-users?hl=en.
