Puppet users - Jan 2011 - puppetdoc - referring to main class

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.

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

This is using puppet 2.6.4-0.5-el5 and ruby-rdoc 1.8.5-5.el5_4.8 on
RHEL 5.

Thanks,

Adrian

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

Posted 5mins too early, found the answer. Hopefully this will help
someone else.

# See example[link:classes/example/example.html]

HTH,

Adrian

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

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