[Pkg-puppet-devel] Bug#616548: please ship upstream documentation for offline reading

Micah Anderson micah at riseup.net
Sun Sep 30 02:29:12 UTC 2012


Hi hi zack!

> As per subject, it would be wonderful to have a puppet-doc package shipping the
> documentation available at <http://docs.puppetlabs.com>.  Rationale: although
> online documentation is handy, sometimes it's really useful to have
> documentation available for offline reading.  (Bonus point if, in doing that,
> you also register it with doc-base, that would be awesome!)

that would be nice! So nice that I started to go down that path to create that
lovely package. Unfortunately, it wasn't long until I was tearing my hair out
and putting out my eyes.

I got the upstream git repository from github, there are no releases, so that is
pretty annoying, but I can live with that. I created a git repository underneath
the puppet git hierarchy in alioth
(git://git.debian.org/collab-maint/puppet-doc.git). That all went well, not a
surprise there. It quickly went downhill once I started to look at the
README.markdown.

First I found that you have to initialize git submodules, to pull in some other
repositories, I really dont have any clue how to deal with that in a debian
package. It is just for the marionette-collective, but sadly it is the entire
source repository for that projcet. Errr.... so I just ignore that for now. Then
it helpfully suggests the various packages that need to be installed, those are
easily added to debian/control, thats easy, maybe things wont be that bad. But
then it starts talking about the ruby gems that are needed, about half of those
exist as packages, the rest don't, err ok....

Lets pretend that never happened, and continue looking at things. The next step
details how you need to run 'rake generate' and then:

2.  Start a little server to view it at http://localhost:9292:

        $ rake serve

oh my.

I think this is where I started to talk like chewbacca, and people around me
began to worry about my sanity.

I decided to keep ignoring things and moved on to other steps, hey maybe I can
just build and ship the HTML pages. All I need to do is:

Build Updated HTML Manpages
---------------------------

    $ PUPPETDIR=~/Documents/puppet rake update_manpages

You will need to point the PUPPETDIR environment variable at a git checkout of
the Puppet code

Oh. That is not nice. I need a checkout of the puppet source to build this? This
is where I turned into the hulk and smashed many, many buildings. I requested
the damage bill sent to Debian, I hope that is ok.

Once I calmed down, I decided that maybe I could just jam all the markdown
source files into /usr/share/doc/puppet-doc and then go home and cry in the
corner. Then I found that the source package has all kinds of stuff, like
unlicensed fonts, javascript and PDFs without source, and the mess was just too
much.

I'm pushing the git repository now, and going to have a beer and squash some RC
bugs instead!

micah
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 801 bytes
Desc: Digital signature
URL: <http://lists.alioth.debian.org/pipermail/pkg-puppet-devel/attachments/20120929/e635efe6/attachment.pgp>


More information about the Pkg-puppet-devel mailing list