On Thu, July 26, 2007 12:46 pm, Phillip J. Eby wrote: At 03:02 AM 7/26/2007 -0500, Dave Peterson wrote: >>Over on the enthought-dev mailing list we're having a bit of a >>discussion on what the best way to distribute documenation and examples >>is for projects that we distribute binary eggs for. The general >>consensus is that it would be very nice indeed if there was a way to >>generate a tarball, or platform install, of just documentation and >>examples so that people wouldn't need to download a full, presumably >>significantly larger, source tarball. Another option would be that >>eggs included the documentation and examples and that, during the >>installation of the egg, those docs and examples were relocated to a >>common location (outside of the zip) to make access by users more >>convenient. This latter idea is similar to how Ruby Gems deal with docs. >> >>I don't claim to be a distutils or setuptools guru, so it shouldn't be >>too surprising that I can't seem to find anything about a setuptools or >>distutils command to do either of these. Am I missing something?
>There are a few different ways you could do this. The easiest would >be to put a docs subdirectory either inside one of your packages or >inside your .egg-info directory, then use the pkg_resources resource >or metadata APIs to list and extract them. One advantage to using >something like .egg-info/docs would be that this could perhaps be >recognized by some sort of "standard" tools in the future. >If not, does it seem like something that might be worthy of putting into >setuptools? >It might be worth establishing convention(s) for, yes. Tools could >then be developed around them, including perhaps changes to easy_install. This relates to a question I asked this list earlier this month (but didn't get a response). For Linux systems the Linux Standards Base references the Unix Filesystem Hierarchy Standard (that applies to all Unix systems as well). The FHS specifies that documentation files (other than specially formatted items like man pages) go into /usr/share/doc/package_name_and_version These sometimes include examples, demos, and similar files. For example, the docs on my FC5 system for inkscape go in /usr/share/doc/inkscape-0.45.1. In that case the doc files are a typical minimal set: /usr/share/doc/inkscape-0.45.1/AUTHORS /usr/share/doc/inkscape-0.45.1/COPYING /usr/share/doc/inkscape-0.45.1/ChangeLog /usr/share/doc/inkscape-0.45.1/NEWS /usr/share/doc/inkscape-0.45.1/README and the examples, tutorials, clipart, and many miscellaneous files are in /usr/share/inkscape. The actual executables are in /usr/bin. In some cases the documentation is created as a separate package. For example, Python does this for its html-based docs and on my FC5 system, the python html docs are in /usr/share/doc/python-docs-2.4.3/. Similar considerations go to configuration files that are supposed to go into /etc. There are a number of other rules, and they are generally observed by systems that use rpm and deb packaging such as Fedora and Ubuntu. I couldn't figure out how to make this happen when using bdist_rpm, which is why I asked the earlier question. It seems to me that the only way using current Python packaging features would be to put the docs somewhere in the Python site-packages hierarchy and do a post-install scripted move to where they belong under the LSB/FHS rules. It would be preferable to get them to go where they belong without the need for post-install scripting. Stan Klein _______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
