[Distutils] Best practices for creating eggs?
Phillip J. Eby
pje at telecommunity.com
Wed Jun 28 23:41:26 CEST 2006
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.)
More information about the Distutils-SIG