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
_______________________________________________
Distutils-SIG maillist - [email protected]
http://mail.python.org/mailman/listinfo/distutils-sig
