pocco - a puppet manifest documentation experiment

[Nan Liu]

Hi!

The existing puppet manifests documentation generated via rdoc isn't
very dry. I quite like docco generated documentation so I borrowed
from rocco to create a puppet manifests documentation tool called
pocco.

Here's a module that will install the tool:
https://github.com/nanliu/puppet-pocco

Here's a sample documentation generated from the manifest in the module:
http://nanliu.github.com/puppet-pocco/

WARNING: unless pymentize is installed, manifests are shipped to
pygments.appspot.com for highlighting, so don't try this on anything
sensitive.

It's just an experiment, but feel free to provide feedback.

Thanks,

Nan

[Ryan Coleman]

On Thu, Oct 18, 2012 at 10:06 PM, Nan Liu <n...@puppetlabs.com> wrote:

Hi!

The existing puppet manifests documentation generated via rdoc isn't
very dry. I quite like docco generated documentation so I borrowed
from rocco to create a puppet manifests documentation tool called
pocco.

Awesome Nan! What's the usage for this? Is one to run rocco against a manifest?

 

Here's a module that will install the tool:
https://github.com/nanliu/puppet-pocco

Sweet! Would you please throw this up on the Forge?

 

Here's a sample documentation generated from the manifest in the module:
http://nanliu.github.com/puppet-pocco/

This is very slick. Is there an option to get the documentation back without the manifest code if that's desired?

 

WARNING: unless pymentize is installed, manifests are shipped to
pygments.appspot.com for highlighting, so don't try this on anything
sensitive.

It's just an experiment, but feel free to provide feedback.

Would anyone be interested in seeing the Forge processing documentation like this and displaying it on a module page? This tool is very manifest centric so the challenge would be to compose module-wide documentation in a meaningful way but this is the awesome-sauce.

 

Thanks,

Nan

--
Ryan Coleman | Modules & Forge @PuppetLabs

Want to get a hold of me?

  - @ryanycoleman on Twitter

  - ryancoleman in #puppet on Freenode

  - https://tungle.me/ryanycoleman to schedule a Skype meeting

 

[llowder]

Comments in line

On Friday, October 19, 2012 12:11:59 PM UTC-5, Ryan Coleman wrote:

On Thu, Oct 18, 2012 at 10:06 PM, Nan Liu <n...@puppetlabs.com> wrote:

Hi!

The existing puppet manifests documentation generated via rdoc isn't
very dry. I quite like docco generated documentation so I borrowed
from rocco to create a puppet manifests documentation tool called
pocco.

Awesome Nan! What's the usage for this? Is one to run rocco against a manifest?

I would like to know this as well, though from looking at the code, I think I saw an exec that updates the documentation if any of the manifests on the master changes.
 

 

Here's a module that will install the tool:
https://github.com/nanliu/puppet-pocco

Sweet! Would you please throw this up on the Forge?

+1
 

 

Here's a sample documentation generated from the manifest in the module:
http://nanliu.github.com/puppet-pocco/

This is very slick. Is there an option to get the documentation back without the manifest code if that's desired?

+1
 

 

WARNING: unless pymentize is installed, manifests are shipped to
pygments.appspot.com for highlighting, so don't try this on anything
sensitive.

It's just an experiment, but feel free to provide feedback.

Would anyone be interested in seeing the Forge processing documentation like this and displaying it on a module page? This tool is very manifest centric so the challenge would be to compose module-wide documentation in a meaningful way but this is the awesome-sauce.

I think that would be an excellent addition to the forge, and would go a long way towards helping decide which modules are good quality and will work with a given site, especially if it can be expanded to cover full modules.
 

[Nan Liu]

On Fri, Oct 19, 2012 at 10:11 AM, Ryan Coleman <ry...@puppetlabs.com> wrote:
> Awesome Nan! What's the usage for this? Is one to run rocco against a
> manifest?

Run pocco against a modules directory:

pocco /etc/puppet/modules/<modulename>

I'm guessing this is making a bit much in assumptions. Might need to
enable runs against a manifests.

And to explain the format a bit:

# markdown
class or define <name> (
$var = default, #: var comment (note it's #:)
) {
...
#normal comments
...
}

pocco will generate

### class/define <name>
markdown
### variables
* [var]: var comment (default)
### usage
import matching tests/*.pp file

normal comments

>> Here's a module that will install the tool:
>> https://github.com/nanliu/puppet-pocco
>
> Sweet! Would you please throw this up on the Forge?

Yes, I'll cut a version and upload it.

>> Here's a sample documentation generated from the manifest in the module:
>> http://nanliu.github.com/puppet-pocco/
>
>
> This is very slick. Is there an option to get the documentation back without
> the manifest code if that's desired?

No, not at the moment. The comments with the code would lose context,
but maybe a header only documentation makes sense.

Nan

[Joe Topjian]

Hi Nan,

Like everyone else, I think this is great. 

 

Run pocco against a modules directory:

pocco /etc/puppet/modules/<modulename>

Just a quick comment: Isn't pocco the name of the Python *occo? (http://fitzgen.github.com/pocco/) should the name be changed to differentiate?

 

Joe

--
Joe Topjian

Systems Administrator

Cybera Inc.

www.cybera.ca

Cybera is a not-for-profit organization that works to spur and support innovation, for the economic benefit of Alberta, through the use of cyberinfrastructure.

[Nan Liu]

On Fri, Oct 19, 2012 at 11:09 AM, Joe Topjian <joe.t...@cybera.ca> wrote:
> Hi Nan,
>
> Like everyone else, I think this is great.
>
>>
>> Run pocco against a modules directory:
>>
>> pocco /etc/puppet/modules/<modulename>
>
>
> Just a quick comment: Isn't pocco the name of the Python *occo?
> (http://fitzgen.github.com/pocco/) should the name be changed to
> differentiate?

Ah, didn't realize that, ppocco =), any other suggestions?

Nan

[Pieter van de Bruggen]

On Fri, Oct 19, 2012 at 11:09 AM, Joe Topjian <joe.t...@cybera.ca> wrote:

Hi Nan,

Like everyone else, I think this is great. 

 

Run pocco against a modules directory:

pocco /etc/puppet/modules/<modulename>

Just a quick comment: Isn't pocco the name of the Python *occo? (http://fitzgen.github.com/pocco/) should the name be changed to differentiate?

It is; the *occo convention is usually used to designate which language/framework the pan-lingusitic Docco clone is written in (see also Rocco [Ruby], Shocco [Shell], Nocco [.NET]).  Since this isn't intended to be a general-purpose Docco clone, it might make sense to buck the convention all-together.

Joe

--
Joe Topjian

Systems Administrator

Cybera Inc.

www.cybera.ca

Cybera is a not-for-profit organization that works to spur and support innovation, for the economic benefit of Alberta, through the use of cyberinfrastructure.

--
You received this message because you are subscribed to the Google Groups "Puppet Users" group.
To post to this group, send email to puppet...@googlegroups.com.
To unsubscribe from this group, send email to puppet-users...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.

[Erik Dalén]

pucco? :)