Ask Your Question
0

How to write documentation for modules?

asked 2015-01-23 02:51:58 -0500

Tomasz Olszewski gravatar image

updated 2015-01-23 10:10:41 -0500

Hello,

I have 2 quite large puppet modules.

My problem - how to create documentation for puppet modules, that will be:

  • Easy to maintain
  • Easy to read
  • Easy to write
  • Beautiful

At this moment I created README file with a lot of plain text + couple of comments on top of each class file.

What I would like to achieve - keep all comments in code, not on the top, or bottom - but inside of code, and use some kind of tool that will generate beautiful HTML/PlainText documents basing on them.

Is anything like this for Puppet? E.g. like doxygen

edit retag flag offensive close merge delete

2 Answers

Sort by ยป oldest newest most voted
0

answered 2015-04-22 08:04:27 -0500

Seb042 gravatar image

updated 2015-04-22 10:42:08 -0500

GregLarkin gravatar image

The problem seems that puppet doc doesn't "see" resources that are declared in a case statement, like this :

case $operatingsystem {
                'centos','redhat': {
                          file { '/tmp/dummy':
                           ...
                           ...
                          }
                 }
                 'solaris': {
                           file { '/tmp/otherfile':
                            ...
                            ...
                            }
                 }
                 default: { 
                 }
}
edit flag offensive delete link more
0

answered 2015-01-23 16:15:49 -0500

GregLarkin gravatar image

This is the currently recommended best practice for creating documentation in your code: https://docs.puppetlabs.com/guides/style_guide.html#puppet-doc.

Once you've added documentation to your classes, you can generate doc pages with the puppet doc command.

edit flag offensive delete link more

Comments

With the release of Puppet 4, `puppet doc` no longer works and has been replaced by the `puppetlabs-strings` module: http://docs.puppetlabs.com/puppet/4.0/reference/release_notes.html#break-puppet-doc-and-tagmail-removed-from-core-released-as-modules

csharpsteen gravatar imagecsharpsteen ( 2015-04-22 09:06:17 -0500 )edit

Your Answer

Please start posting anonymously - your entry will be published after you log in or create a new account.

Add Answer

Question Tools

1 follower

Stats

Asked: 2015-01-23 02:51:58 -0500

Seen: 400 times

Last updated: Apr 22 '15