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