Puppet users - Oct 2012 - pocco - a puppet manifest documentation experiment

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

-- 
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 Thu, Oct 18, 2012 at 10:06 PM, Nan Liu <nan@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

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

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<javascript:>
> > 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.
 
>  
>
>>
>> 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
>  
>
>
>
-- 
You received this message because you are subscribed to the Google Groups
"Puppet Users" group.
To view this discussion on the web visit
https://groups.google.com/d/msg/puppet-users/-/5mFm-3KScW4J.
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 Fri, Oct 19, 2012 at 10:11 AM, Ryan Coleman <ryan@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

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

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.

-- 
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 Fri, Oct 19, 2012 at 11:09 AM, Joe Topjian <joe.topjian@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

-- 
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 Fri, Oct 19, 2012 at 11:09 AM, Joe Topjian <joe.topjian@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-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.
>
-- 
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 Friday, 19 October 2012 20:11:51 UTC+2, Nan Liu
wrote:
>
> On Fri, Oct 19, 2012 at 11:09 AM, Joe Topjian
<joe.t...@cybera.ca<javascript:>>
> 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? 
>
>
pucco? :)

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