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 [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.
