[Distutils] Best practices on distributing documentation and examples with eggs?

[Stanley A. Klein]

On Thu, July 26, 2007 9:50 pm, Phillip J. Eby wrote:
>At 02:13 PM 7/26/2007 -0500, Dave Peterson wrote:
>>In further discussions at Enthought, we're now thinking that creating a
'docs' dir as a top-level under python itself makes sense, and then the
installation of eggs could copy docs and/or examples there in a manner
similar to how it handles scripts into the platforms scripts dir.   It
would make sense that they should be put in dirs named with a format
like <project name>-<version> so that the user could differentiate the
docs for each project they installed.  If this was done, it seems like
it wouldn't be too hard for Stan, and other rpm builders, to either
create symbolic links or copy these to /usr/share/doc in order to
maintain compatibility with the LSB.

>This isn't a bad idea, although I think that there are some hurdles  that
need to be worked out.  My general thought is that, were
>easy_install to support documentation, it would need to take an
>option to determine the documentation base directory, and have a 
--no-docs install option.

>One issue is that under most RPM systems, package names are more like 
'python-foobar-1.2', and 'foobar' may not even be the exact distutils 
name of the package.  So, installing the docs to the correct location  in
the general case may be more complex.  Note, however, that
>bdist_rpm offers a --doc-files option, which of course can be
>configured via setup.cfg.  I have no idea how it works, though, so  don't
ask me.  :)


The practice of changing the name of the whatever package to
python-whatever may be distro dependent.  Also (thankfully),
python-whatever is installed in site-packages/whatever and not in
site-packages/python-whatever.  It was not always that way.  Back at
something like RedHat 7, they did change the names and the installation
locations.  If you had another program that imported the package, you
sometimes had to go in and change the code to match their changed name.

I can understand the reasons of the distros and repositories for doing
this (keeping all the python or other language packages together in the
list) but that does not make it less annoying.  In looking to see if a
package is in the repository, you have to look in various places beyond
what the original developer/maintainer of the package calls it.

Also, I'm not sure of the split between /usr/share/whatever and
usr/share/doc/whatever for things like docs, tests, examples, and other
miscellaneous files.  It tends to be at the whim of the packager.

In terms of what bdist_rpm does, it seems to be in the preparation of the
rpm spec file.  The spec file contains scripts (some of which point to
macros in /usr/lib/rpm/macros on a Fedora system) and bdist_rpm seems to
build the scripts and execute them using rpm-build.  The build and install
scripts do "python setup.py build" or "python setup.py install" with
whatever options are specified.  I think the actual location of the files
may be governed by the %files section of the spec, but I will have to
spend some time looking at other spec files to be sure that is where it
happens.


Stan Klein


-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.python.org/pipermail/distutils-sig/attachments/20070802/c75904a6/attachment.html