Re: [Distutils] layout and setup.py for packaging documentation
At 10:39 PM 2/28/2010 +0000, Michael Foord wrote:
On 28 February 2010 22:14, P.J. Eby <<mailto:pje@telecommunity.com>pje@telecommunity.com> wrote: At 10:03 PM 2/28/2010 +0100, Jean Daniel wrote: Can this be simpler?
Yes. Don't install docs with your package. People who want them installed locally can just download your source install or use easy_install -e.
Also, if your module is popular enough that people make Linux system packages for it, they will make sure the docs get put in a blessed install location. Python doesn't currently have a blessed install location for documentation, though perhaps it *should* have one in distutils2.
How to include documentation in a package is a common question, so it would be great if distutils2 could deal with this issue.
My current solution is, as Phillip suggests, to not include the docs in distributions available via PyPI and to provide a more 'complete' download separately.
That's not what I suggested, actually. I said, don't *install* docs with your package. Do *include* them in your source distribution, though, so people can download and read them with easy_install -e, and also so that those system packagers only have to download one tarball. You also need only produce a standard source distribution (setup.py sdist upload) for PyPI. 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.
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
participants (2)
-
Marius Gedminas -
P.J. Eby