FAQ
Starting this thread to discuss changes to puppet doc as was recommended in
a different thread.

Once I finally got the rdoc documentation generation working, I rather like
it. Especially when paired with The Foreman.

It would be nice if the help was clearer, and it was easier to find a list
of the gems/tools that are required to be able to use it. Or better yet, if
they were included when you installed the puppet package.

Being able to generate PDF files would be very helpful, as they are easy to
print, and also easy to move around or have as a reference on a mobile
device (such as phone or personal laptop) that may not have network access
to the puppet master.

As far as the rdoc thing, it's fine with me, but it would be nice if there
was a way to scrape params from the classes w/o having to list out each in
the comments, which I think is part of the actual Ruby rdoc functionality.

- Lee

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

  • Ken Barber at Jul 20, 2012 at 9:47 pm

    As far as the rdoc thing, it's fine with me, but it would be nice if there
    was a way to scrape params from the classes w/o having to list out each in
    the comments, which I think is part of the actual Ruby rdoc functionality.
    Yeah - repeating yourself is awful. /me has written quite a few puppet
    doc headers in my time and this is a pet peave. On this line of
    thought - I'd prefer to have it grok the description of the param from
    a comment field near the property/param or something (like above?),
    this would feel more natural.

    ken.

    --
    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.
  • Nick Fagerlund at Jul 20, 2012 at 9:56 pm
    Manually generating module docs is kind of a drag. It'd be cool to have
    them served dynamically directly from the modulepath, with some kind of
    simple web app. (I think Nigel has already mentioned this internally, but I
    wanted to get it out in the public thread too.)

    --
    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/-/CmMmLsI120YJ.
    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.
  • Giovanni Torres at Jul 20, 2012 at 10:59 pm
    Lee,

    You have some good points. The Rdoc to html conversion is nice. You can
    put it on an internal webserver and share with other members of your team.
    It is a bit tedious, however, and scraping the params from the classes
    would be a great feature.

    NIST provides guidelines for RHEL, along with many other operating systems
    and applications. I was very excited to see that they are distributing
    puppet modules in conjunction with the typical, unwieldy spreadsheet to
    demonstrate the changes! (
    http://usgcb.nist.gov/usgcb/rhel/download_rhel5.html)

    Puppet is touted as self-documenting, but what happens when we want to
    print out the documentation or incorporate into our existing documentation
    formats?

    I use Sphinx for documentation which is based on the fairly simple RST
    format. I'm sure people out there use a variety of documentation
    applications to wrangle all their IT docs in one central place. I often
    update my documentation and periodically print it out and create a binder
    for reference. I would love to be able to append my puppet modules to this
    binder. This would make my documentation whole!

    Before I drift, it seems there are different ideas within the doc module.
    Here are a few of my thoughts as to how puppet-doc could be useful to me
    and others similarly (hopefully):

    * Semi-automated rdoc markup generation would be nice.
    * An option to output documentation in multiple formats, such as (rdoc,
    rst, pdf, html, etc.)
    * An option to convert everything under a single module/ directory directly
    to output format of choice
    * An option to convert all documentation under /etc/puppet to output of
    choice

    I'm sure others have some other cools ways of how they can use this module.
    Please contribute your ideas and help shape this useful feature.

    Giovanni
    On Friday, July 20, 2012 5:43:01 PM UTC-4, llo...@oreillyauto.com wrote:

    Starting this thread to discuss changes to puppet doc as was recommended
    in a different thread.

    Once I finally got the rdoc documentation generation working, I rather
    like it. Especially when paired with The Foreman.

    It would be nice if the help was clearer, and it was easier to find a list
    of the gems/tools that are required to be able to use it. Or better yet, if
    they were included when you installed the puppet package.

    Being able to generate PDF files would be very helpful, as they are easy
    to print, and also easy to move around or have as a reference on a mobile
    device (such as phone or personal laptop) that may not have network access
    to the puppet master.

    As far as the rdoc thing, it's fine with me, but it would be nice if there
    was a way to scrape params from the classes w/o having to list out each in
    the comments, which I think is part of the actual Ruby rdoc functionality.

    - Lee
    --
    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/-/bZRAsobu0kgJ.
    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.

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
grouppuppet-users @
categoriespuppet
postedJul 20, '12 at 9:43p
activeJul 20, '12 at 10:59p
posts4
users4
websitepuppetlabs.com

People

Translate

site design / logo © 2022 Grokbase