[Distutils] Best practices for creating eggs?

[Phillip J. Eby]

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.)