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

Search Discussions

  • Ryan Coleman at Oct 19, 2012 at 5:38 pm

    On Thu, Oct 18, 2012 at 10:06 PM, Nan Liu 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.
  • Llowder at Oct 19, 2012 at 5:19 pm
    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.
  • Nan Liu at Oct 19, 2012 at 6:20 pm

    On Fri, Oct 19, 2012 at 10:11 AM, Ryan Coleman 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.
  • Joe Topjian at Oct 19, 2012 at 6:37 pm
    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.
  • Pieter van de Bruggen at Oct 19, 2012 at 6:12 pm

    On Fri, Oct 19, 2012 at 11:09 AM, Joe Topjian 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.
  • Nan Liu at Oct 19, 2012 at 6:17 pm

    On Fri, Oct 19, 2012 at 11:09 AM, Joe Topjian 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.
  • Erik Dalén at Jan 28, 2013 at 9:50 am

    On Friday, 19 October 2012 20:11:51 UTC+2, Nan Liu wrote:
    On Fri, Oct 19, 2012 at 11:09 AM, Joe Topjian 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.

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
grouppuppet-users @
categoriespuppet
postedOct 19, '12 at 5:06a
activeJan 28, '13 at 9:50a
posts8
users6
websitepuppetlabs.com

People

Translate

site design / logo © 2022 Grokbase