[Distutils] [zc.buildout] general doc sprawl
Philipp von Weitershausen
philipp at weitershausen.de
Thu Jul 17 06:25:28 CEST 2008
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
More information about the Distutils-SIG
mailing list