[Distutils] [zc.buildout] general doc sprawl

[Philipp von Weitershausen]

Chris Withers wrote:
> 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.

I agree. This "README.txt" isn't really a good primer on zc.buildout 
anymore. Well, honestly, it never was. It should just be renamed so we 
can stop pretending it was a 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..)

http://grok.zope.org/documentation/tutorial/introduction-to-zc.buildout

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

bin/buildout --help  ???

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

You're several orders of magnitude off :). PyPI counts 99 recipes 
(http://pypi.python.org/pypi?:action=browse&show=all&c=512) and there 
aren't that many that provide the same kind of functionality. So why not 
jus try out a recipe when you need its functionality. If any of these 
were indeed written by "muppets", you'd find out pretty quickly, no?

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

http://www.google.com/search?q=buildout+cmmi+recipe