Ask Your Question
0

Document modules with YARD or as README.MD

asked 2016-12-21 20:36:50 -0500

AFAIK, forge.puppetlabs.com only renders the readme.md along the module description. However, I've noticed there's something in the works: There was a puppetlabs/strings module, which now is a Ruby gem. And in the long run puppet module documentation is done via YARD documentation strings.

That's great. However, I haven't found any clue, that PuppetForge goes along with this development and respects YARD documentation strings. Do I write my module documentation still as readme.md for now, or should I switch to YARD? How long does it take, until YARD documentation is propagated as new standard?

Because, I don't like to document, publish my great module, and some months later Forge considers YARD documentation, too. On the other, a YARD only documented module doesn't “sell”, since it's got a pretty empty readme.md. I'd place a hint “I did a great job with YARD”, but it doesn't show up on the module description page on Forge. ☹

edit retag flag offensive close merge delete

1 Answer

Sort by » oldest newest most voted
0

answered 2016-12-22 12:58:21 -0500

The Forge also extracts and displays docstrings from Resource Types. My hope is that we'll see that same level of integration for classes, etc. too.

edit flag offensive delete link more

Comments

Yeah, resource types written in Ruby. Which are placed in the `lib/` module's subdirectory. I still write most things in the Puppet language though.

Kai Burghardt gravatar imageKai Burghardt ( 2016-12-22 14:37:31 -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: 2016-12-21 20:36:50 -0500

Seen: 49 times

Last updated: Dec 22 '16