[Distutils] layout and setup.py for packaging documentation

[P.J. Eby]

At 10:39 PM 2/28/2010 +0000, Michael Foord wrote:
>On 28 February 2010 22:14, P.J. Eby 
><<mailto:pje at telecommunity.com>pje at 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.