Re: Can't create pdf from puppet doc

[llo...@oreillyauto.com]

On Monday, July 16, 2012 9:50:54 AM UTC-5, Giovanni Torres wrote:

I'm trying to use puppet doc to create a pdf version of my modules.  According to the help file, `puppet doc -m pdf -r configuration` is the syntax to accomplish this.  However, I keep getting this error:

creating pdf

Could not run: wrong number of arguments (1 for 2)

I've been having this same problem, and have previously asked for help on this list to no avail.

If you do find a solution, please share, as it would be much appreciated.
 

I search elsewhere on the web for others having a similar issue with pdf generation, but no real luck finding a solution.

I am running CentOS 6 with

ruby-1.8.7

puppet-server-2.7.18

Is this a bug?  I did not find a bug describing this issue in the Issues section of the Puppet website.

Is there a --verbose or --debug that I could use with `puppet doc`?

[Giovanni Torres]

I installed puppetd/puppetmasterd on an OpenBSD laptop and tried the same command:

    sudo puppet doc -m pdf -r configuration

...and I get a little further with a different error:

    creating pdf

    /tmp/puppetdoc.txt:1198: (ERROR/3) Unknown target name: "confdir"

The puppetdoc.txt file that gets generated in /tmp before actually creating the pdf has this near line 1198:

    ### vardir

    Where Puppet stores dynamic and growing data.  The default for this parameter 

    is calculated specially, like `confdir`_.

    - *Default*: /var/puppet

Why is it so hard just to convert to pdf?  I tried on CentOS 6 and OpenBSD 5.1 ... no dice.  Is it just me? Am I missing some external package that is causing this error?  It had previously complained about not finding the rst2latex command, but I got past that error by downloading the docutils package.

Anyone getting this to work without issue on CentOS 6 or OpenBSD 5.1?

[Nick Fagerlund]

Here's your problem: puppet doc is actually TWO tools, both of which have major problems right now. You're mixing up invocations of the two. Which is a perfectly reasonable mistake and not really your fault. Anyway, the upshot is that you CAN'T generate PDFs from your module documentation. The tool just has never been able to do that.

Puppet doc's two uses are:

* Module docs, for use by Puppet users -- extracts rdoc strings from comments and metadata about your classes and defined types, and builds an rdoc-style website. Can ONLY build a website. That's all it does.

* Puppet reference generation, for use by Puppet Labs employees -- extracts Markdown fragments from the Puppet code around config settings (that's the command y'all were trying to use), types and providers, functions, and some more esoteric stuff like indirections.  Can build larger Markdown documents and I guess it maybe used to be able to build a PDF, but if so it's been super-busted for a WHILE, since it seems to be expecting RST input and we switched to Markdown fragments before I even joined the company.

Obviously these are completely unrelated, and having them mixed in the same tool is dumb. We need to separate them.

Anyway, back to the point: I recommend that you start a new thread on this group talking about what you and your people need in terms of module documentation formats. Ryan Coleman, the product owner for modules and the Puppet Forge, is the person who will be figuring out our requirements for that tool going forward, and I think he's already been doing some thinking about it, but he could use your input and real-life use cases. What makes a PDF of module docs a good fit for your site? What else could fit those needs? Do you want to be able to write your comments in something other than Rdoc format? That kind of thing.

Sorry for the downer, and for the confusing nature of the tool!

N
Puppet Labs docs team

[Ryan Coleman]

On Fri, Jul 20, 2012 at 2:25 PM, Nick Fagerlund
<nick.fa...@puppetlabs.com> wrote:
> Anyway, back to the point: I recommend that you start a new thread on this
> group talking about what you and your people need in terms of module
> documentation formats. Ryan Coleman, the product owner for modules and the
> Puppet Forge, is the person who will be figuring out our requirements for
> that tool going forward, and I think he's already been doing some thinking
> about it, but he could use your input and real-life use cases.

Yep, thanks Nick!

I have indeed been thinking about this tool a lot lately and will be
getting some improvements to it into the pipeline soon. To that end,
I'd absolutely to hear more about what you want to achieve. Nevermind
what the tool does today.. what did you want to do with it?

As Nick said, starting a new thread about what you want from the tool
would be awesome. Please do!

[llo...@oreillyauto.com]

I have started a new thread for this purpose, called "Documentation Requirements."

On Friday, July 20, 2012 4:41:58 PM UTC-5, Ryan Coleman wrote:

[Giovanni Torres]

Thanks for clearing this up.  The puppet-doc man page has the following example:

'puppet doc -m pdf -r configuration'

This led me to believe that it converts different portions to pdf.  Regardless.  Documentation is always useful and I will contribute my ideas to the new thread.

Thanks.