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 setup.py 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()
   
   setup(name='collective.types.citation',
       version=version,
       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::
          [instance]
          recipe = plone.recipe.zope2instance
          ...

      • This was valid:

        * Tell the plone.recipe.zope2instance recipe to install a ZCML slug::
           [instance]
           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.

      easy_install-2.4 doctuils
      python2.4 setup.py --long-description | rst2html.py > longdescription.html

6. I uploaded my new egg from inside the top level of my package, src/collective.types.citation

   python2.4 setup.py 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:

   [server-login]
   username: your-username
   password: your-password

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

Notes

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.