[Distutils] layout and setup.py for packaging documentation

[Marius Gedminas]

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.

Right.

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':
http://bazaar.launchpad.net/~mgedmin/gtimelog/trunk/annotate/head:/Makefile

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>