[Distutils] [zc.buildout] general doc sprawl

[Chris Withers]

Hi All,

If you go to http://pypi.python.org/pypi/zc.buildout/1.0.6
the resulting page is *huge* :-(

There doesn't appear to be any real structure to it and it reads as if 
it's been added to by various different authors over time. It also seems 
to be a good example of "doctests gone wrong" where the doc has become 
less important than the test.

Of particular difficulty is that sections often seem to refer to 
concepts that are only introduced further down in the document.

As someone trying to learn buildout in depth, what I'd most like is:

- a short tutorial introduction (this bit is there, I think..)

- a list/reference of the options passable when running buildout
   (I think this appears about 30% of the way through that doc, but I'm
    not sure all the options are covered)

- a list/reference of the "commands" buildout has. I counted "install"
   and "init" and maybe "bootstrap" too, but I don't know if that's all
   and I'm still hazy about what the differences are between each one.

- a list/reference of the options names that have meaning in the
   [buildout] section to buildout itself. There seem to be a *lot* of
   these and they're scattered throughout the document at that URL. I
   have a horrible sinking feeling that I'm going to spend most of my
   life with buildout trying to find the right option name to use :-/

- now, and now only, docs on how to write recipes and then on to the 
more esoteric stuff, although I suspect the references above would 
likely cover a lot of it.

It'd also be great it it wasn't just one monolithic file, but I guess 
that's just my reading preference :-S

I'm afraid I'm unable to offer resources to try and fix this problem but 
I do feel it should be highlighted as it makes buildout, which now that 
I'm finally getting over the documentation barrier, seems to actually be 
a very sturdy and useful tool (and gets over some of the setuptools, egg 
and pypi suck), exponentially less easy to play with for newbies.

Oh, and a parting shot: it would be great to get some idea of the "known 
good" recipe types to use too. I see the plone guys have vomited several 
million recipe eggs into pypi and, to be blunt, it's impossible to 
figure out which were written by muppets and which by people with 
functioning brains.

Someone mentioned a cmmi recipe at EPC. That sounded interesting but now 
I don't know where to find it...

drowning-ly yours,

Chris

-- 
Simplistix - Content Management, Zope & Python Consulting
            - http://www.simplistix.co.uk