Creating a Plone Egg

I remember having some difficulty creating an egg several months ago.  I’m not sure if it’s gotten easier, or if I was just missing something in the tutorials that I read at the time.  Therefore, I’m creating a step-by-step set of instructions for how I created my first successful Plone egg.  Note that I tried to use iw.releaser, but my easy_install doesn’t seem to like it.  I don’t think it’s an iw.releaser bug, I think I messed up my easy_install.

I’m running on Ubuntu 8.10 Intrepid Ibex.  I used Martin Aspeli’s instructions on the Plone site for this process.

  1. I created my package using paster.
    paster create -t plone collective.types.citation
  2. I got my package working how I wanted it, and ready for a beta release.  This includes passing tests!  Make sure your tests all pass before you create your egg.
  3. Per Martin’s instructions, I moved my setup.cfg file to another location temporarily.
  4. I changed my to include my docs/* files for the long_description instead of a text string within the file.
    from setuptools import setup, find_packages
    import os
    version = '9.01'
    def read(*pathnames):
        return open(os.path.join(os.path.dirname(__file__), *pathnames)).read()
        description='Citation content type',
        long_description=''.join((read('docs', 'README.txt'),
                                                  read('docs', 'HISTORY.txt'),
                                                  read('docs', 'INSTALL.txt'),
                                                  read('docs', 'CUSTOMIZATION.txt'),
                                                  #Add any additional files in your docs folder here
  5. I updated my docs/* files with relevant information.  I made sure they were structured with headers and subheaders in the locations I wanted using reST.
    1. One thing that took me a big to figure out was the structure for code within the docs/* files.  If you want to include some code, put a double colon :: on the line before your code.  The following line will be code, and should be indented from the previous line.  Where I ran into trouble was in a bulleted list.  The line is considered to start where the text starts after the bullet.
      • This gave me an indentation error:
        * Tell the plone.recipe.zope2instance recipe to install a ZCML slug::
          recipe = plone.recipe.zope2instance
      • This was valid:
        * Tell the plone.recipe.zope2instance recipe to install a ZCML slug::
           recipe = plone.recipe.zope2instance
    2. I checked my long_description to make sure the reST comes out valid.
      1. I installed docutils and ran setup to see the output that will show up on the pypi page.  Note that this outputs to an html file which can be opened in a browser, if there are errors, they will show in the file.
      2. easy_install-2.4 doctuils
        python2.4 --long-description | > longdescription.html
  6. I uploaded my new egg from inside the top level of my package, src/collective.types.citation
    python2.4 egg_info -RDb "" sdist register upload

    (If you already have an account on pypi, you should be able to log in at this point. If not, you will be given a chance to register.)
    If you don’t want to log in each time, create a .pypirc directory in your home directory, and include this information:

    username: your-username
    password: your-password

    Not that this is stored plain-text and not very secure.


I was having an issue with only *.py files being put into my egg, the *.pt, *.txt, and *.zcml files were being ignored.  I searched all around and couldn’t seem to find anyone else with this issue.  Finally, Tres Seaver had the answer.  I needed to do a subversion checkout, and build the egg with that checkout.  I’ve been using git-svn, which doesn’t actually grab the .svn directories.  Apparently, paste uses the information in the .svn directory to determine which files to add to the egg.  After doing a subversion checkout and running the same command in step 6, my egg built beautifully, and even included the docs directory at the top level of my package 🙂

Thanks, Tres!


~ by Liz on February 10, 2009.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: