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.
      2. 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!

Advertisements

~ by Liz on February 10, 2009.

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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 )

Google+ photo

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

Connecting to %s

 
%d bloggers like this: