[Distutils] layout and setup.py for packaging documentation

Marius Gedminas marius at pov.lt
Mon Mar 1 10:30:07 CET 2010

On Sun, Feb 28, 2010 at 10:49:25PM -0500, P.J. Eby wrote:
> In other words, Jean Daniel should retain his source layout of:
>    wordish-1.0.2/
>         setup.py
>         wordish.py
>         docs/
>             index.html
>             command-ref.html
> And simply make sure that docs/ is under revision control (setuptools) or 
> add a "recursive-include docs" to MANIFEST.in (distutils).  Then, 
> "setup.py sdist" will build a correct tarball.


I'd only like to add that the first solution (revision control magic) is
often fragile: revision control metadata format changes (happened with
subversion twice: 1.4 -> 1.5, 1.5 -> 1.6), or you switch revision
control systems (svn -> bzr/hg) and forget to install the appropriate
setuptools plugin, or you need to make a release on a different computer
that happens not to have the appropriate setuptools plugin.  In the end
it's very easy to produce incomplete sdists and not notice that until
it's too late.

I recommend always writing a MANIFEST.in and perhaps implementing some
sort of 'make distcheck' automated test that builds an sdist, extracts
it, builds a second sdist from the first one, then compares the two to
see if any files are missing.

Here's an example of 'make distcheck':

Please ignore the frothy comment about black magic, I must've been
really frustrated when I wrote it...  Setuptools and the surrounding
ecosystem of packages (PyPI, virtualenv, buildout, pip, Distribute) is
probably the best thing that happened to Python lately, despite
occasional little quirks.

Marius Gedminas
You've obviously never tried to reverse engineer a chip using an electron
microscope. [...] That's like looking at the grains of sand on a beach
and trying to map out the coastline of Hawaii. -- Cutie Pi, July 2006
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
URL: <http://mail.python.org/pipermail/distutils-sig/attachments/20100301/ac693643/attachment.pgp>

More information about the Distutils-SIG mailing list