At 04:39 PM 6/28/2006 -0400, Jim Fulton wrote:

Has anyone written up any best practices for creating eggs?

How do people handle documentation?

I basically make web pages for them, or if it's small enough of a project, stick it in the long_description of setup() (usually by reading it from a README.txt file). Otherwise, I make the documentation home page be easily reachable via information in PyPI (e.g., make it the 'url' in 'setup()'). I assume that most people will read the docs on the web, and that if they want the documentation source, they will download the "sdist" distribution that I always upload alongside of the eggs.

Our packages tend to have documentation files included as doctests, but It's not clear how folks are expected to get to them, especially if the eggs are zip files.

I just post them to the web. In some cases, I have scripts that "svn up" and rebuild the docs nightly. For others with relatively short docs, I just upload them by hand. There's lots of opportunity to add more distutils or setuptools extensions for doc processing. I imagine that Zope projects will probably want to have some declarative or discoverable way to get docs built, so you can automate the process of updating browsable versions of the doc, or for that matter assist people in building their own docs from source. (By the way, "easy_install -eb somedir foo" will download and extract (or check out of Subversion) a copy of "foo" to "somedir/foo", so you are not limited to what is placed in an egg for execution/import purposes; I assume the typical user will read docs online, and thus most installations and downloads do not need to carry substantial documentation.)