On 06/01/11 18:20, Adrian Bridgett wrote:
> I'm being a good boy and using the puppetdoc tool to document my
> classes, however I'm hitting a minor annoyance.
>
> The top level documentation for a module (let's call it "example) is
> pulled from example/README (not example/manifests/init.pp), okay I can
> cope with that.
That's not entirely correct. If there is a readme it will be used, but
still you can use classic comments hooked to the "main" module class:
modules/example/manifests/init.pp:
# Module Example
# This is a good module everyone should use
class example {
}
Just make sure to not put anything between the last comment line and the
"class" identifier.
> The documentation for the class in example/manifests/init.pp ends up
> as example::example (hmm, interesting, I wonder what would happen if I
> had example/manifests/example.pp).
Unfortunately I always found this a little bit strange. Declarations in
the module init.pp are global, unlike any other files in the manifests
subdir.
Since I wanted to make sure that we understand that this main module
class is a module and not a straight class from outside the module
hierarchy, I did arbitrarily (but noone contested afterward so I thought
it was OK) put it in this namespace. Otherwise there wouldn't had any
possibility to distinguish a global class example defined in the global
manifestsdir and the module.
> However if I try and refer to this
> from README I can only get links to the toplevel example doc (i.e.the
> README).
>
> I've tried lots of combinations, I was expecting to use something like
> this in README:
> # Example module - see example::example for default usage
> # If you just want the client use example::client
>
> however whilst "example::client" is a hyperlink to classes/example/
> install.html, the first line is converted into two separate
> hyperlinks, both to classes/example.html.
That looks like a bug to me. Unfortunately we are relying on rdoc to
produce the hyperlinking so it's possible that a bug there prevents it
to work in some cases. I know that some identifiers valid in puppet for
instance don't produce hyperlink because of that.
> This is using puppet 2.6.4-0.5-el5 and ruby-rdoc 1.8.5-5.el5_4.8 on
> RHEL 5.
That's an old rdoc. I don't know if that matters or not though.
Can you file a redmine ticket for this issue?
--
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-us...@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.
