[Zope3-Users] Re: buildout and egg depedencies

[Jeff Shell]

On Dec 12, 2007 3:07 PM, Martin Aspeli <optilude at gmx.net> wrote:
> > The doc-test is difficult to read
> > and speaks in generics, not about day-to-day problems. The Recipes are
> > even worse, leaving one to clamor through the web to get back to the
> > cheeseshop page and then face the same difficult to read doc-test kind
> > of 'help'. Which I wouldn't mind reading, if I could easily read that
> > help locally, like a man page or using Python's 'help()' system.
> > ``buildout help zc.recipe.egg``, ``buildout help zc.recipe.cmmi``,
> > whatever.
>
> +1
>
> In general, once you understand that recipes are just eggs, loaded with
> an entry point, and that options are passed around in dicts-of-dicts, I
> find buildout pretty easy to get to grips with.

I understand that they're eggs with entry points. But that doesn't
help me figure out all of the options available. It's hard to get a
simple straightforward list of a Recipe's configuration options, how
to format them (since the ConfigParser format is so godawful), etc.

I'd love to see something like this:
http://www.kernel.org/pub/software/scm/git/docs/git-checkout.html

description -> options -> and then maybe some details and examples.

But instead I'm scrolling my browser window up and down trying to pick
out mentions of an option, and then squinting to see it in use in a
doc-test block so I can see how it might be formatted. And often then,
the documentation for that feature is broken out like.

    if you set the value to FOO, it does this:

    (40 lines of doctest code block)

    Set it to FOO&BAR to do foobrish things. Let's look at that::

    (43 lines of doctest code block)

I'm not going to read those 40 lines of code, half of which are
manufactured output, because that manufactured output is not something
I'm likely to ever see anyways. If that stuff wants to be further down
the doc, fine. But it's just so hard to figure out at a glance.

Again - I'm glad that there's documentation at all. I'm very glad
doctest exists, as it at least promotes writing prosaic documentation
of how a system works and how to interact. But it would be nice to see
recipe pages start like this:

    zc.recipe.filestorage

    description:
        Specifies the location of a Data.fs as a buildout part, and generates
        some ZConfig data that may be used by other recipes (see
        zc.zope3recipes).

    options:
        path (optional) -- a path to a filestorage instance. If not provided,
        it will be placed in the part directory.

    provides:
        zconfig -- A ZConfig configuration file string containing a path
        to the specified or implied filestorage file. Used by zc.zope3recipes

        path -- The path to the filestorage file.

    examples:

        To have the filestorage in $BUILDOUT/parts/db/Data.fs (or wherever
        the parts directory is configured)::

            [db]
            recipe = zc.recipe.filestorage

        Addressing a specific file::

            [db]
            recipe = zc.recipe.filestorage
            path = /opt/zodb-storage/my-app/app.fs

        Using with a zope3 instance home (using zc.zope3recipes:instance*)

            [instance]
            ... simple instance setup
            zope.conf = ${db:zconfig}

            [db]
            ...

    see also:

        zc.zope3recipes
        zc.zodbrecipes (ZEO configuration)

And the mentions of other recipes could be links. How nice that would
be! (Although, it is pretty easy to put 'zc.zope3recipes' or any other
package name at the end of a cheeseshop url).

Anyways, I know this is selfish wanting on my part. I've just been
relatively surprised by some tools like Git recently where there's a
bounty of help structured like the above.

> > I've gotten Buildout to work on some small components. It's great -
> > check out the source, run buildout, wait, wait, wait, and then have a
> > nice little self contained testing and development environment. But
> > I've never been able to get a full Zope 3 "Application" up and running
> > in that environment.
>
> Have you looked at zopeproject (uses buildout) grokproject (uses
> buildout) or Repoze (uses virtualenv)?

I've looked at zopeproject. The biggest problem is that we have large,
existing applications that don't fit those molds. Starting up a
totally fresh project? Relatively easy.

But just today, I was trying to get a running buildout instance thingy
going for a customer who has a very small site which we haven't yet
deployed. Now I'm just running into problems with finding out which
things are configured (in ZCML) by default and which aren't. And the
last stumbling block I hit before I gave up for the day involved
`zope.filerepresentation` installing as a zipped egg, which then gets
in the way of ZCML being able to load its configure.zcml file. I tried
to find out if there was an 'always_unzip' option for Buildout, but it
seems to only be a part of buildout's easy_install API.

> > There's just no time and the tools are just too hard to learn under
> > the circumstances my little company is operating in right now.
> > Buildout *seems* like it could fix some big problems that have been
> > hitting us hard in recent weeks. But I still can't wrap my head around
> > how.
>
> Maybe you should start a new thread and tell of your use cases and ask
> for examples of how to solve them?

Now that I'm getting farther along, I should be able to do that. If I
have time. Got a lot of pressure things the next couple of days :(.

-- 
Jeff Shell