Hi,
I'm contributing to Puppet a new feature called Manifest Inline
Documentation (see redmine ticket #1664). It is not yet part of the
mainline distribution, but I hope to have it integrated soon.
The purpose of this feature is to extract documentation from puppet
modules or manifests and either produces a browsable HTML content or
directly to the console, in the same way javadoc, RDoc or perldoc are
working.
The documenation must be added in comments preceding language
statements, as in the following (completely dumb) example:
# Class: User
# This class is responsible of creating users in the system
# Warning: users are created without password
class user {
...
}
Right now, the system is able to extract comments from classes,
definitions and nodes. The idea is that you want to document only your
publicly visible class/define (and kind of API) and not how they really
work inside.
You can find a sample that I ran on David Schmidtt's famous modules[3]:
http://www.masterzen.fr/puppet/rdoc/index.html
Note that David's modules _don't_ contain RDoc markup hence the result
is not perfect.
The HTML version is based on RDoc[1] and as such uses the simple markup
language used in RDoc[2].
The development version is hosted on my github branch feature/inline-doc
in the form of a patch against puppet 0.24.x:
http://github.com/masterzen/puppet/tree/feature%2Finline-doc
To get it:
$ git clone git://github.com/masterzen/puppet.git
$ cd puppet
$ git checkout feature/inline-doc
Then to run it on a default installation:
$ RUBYLIB=`pwd`/lib bin/puppetdoc --mode rdoc --outputdir /tmp/rdoc
It will read your current puppet.conf and infer from there modulepath
and manifestdir. It is also possible to use --modulepath and
--manifestidr command-line arguments as puppetmasterd.
Then point your browser to /tmp/rdoc/index.html to see the generated
documentation. Of course you better have some comments for the result to
mean something :-)
Now, why I'm sending this e-mail?
I'm looking for help in several directions:
* find bugs so that I can fix them (I'm sure there are some)
* gather comments and ideas to have a better system, better tailored
to the documentation practices used by the community.
* get a better design from HTML/CSS knowledgeable people to have
something that doesn't look like RDoc.
Then we'll have a chance to get a real good product for mainline
integration.
If you have questions you can answer to this e-mail or contact me on
#puppet (nickname: masterzen).
Thanks for your help and attention,
[1]: RDoc: http://rdoc.sourceforge.net/
[2]: RDoc markup: http://rdoc.sourceforge.net/doc/files/README.html
(see the Markup section).
[3]: David Schmidtth modules:
http://reductivelabs.com/trac/puppet/wiki/CompleteConfiguration
--
Brice Figureau
Days of Wonder
http://www.daysofwonder.com
--~--~---------~--~----~------------~-------~--~----~
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 [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/puppet-users?hl=en
-~----------~----~----~----~------~----~------~--~---
