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

[Dave Peterson]

Stanley A. Klein wrote:
> 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.
>   

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.


One other thought we've been throwing around is an idea of adding 
something to easy-install so that users can still get a minimal binary 
distribution if they want, and then, if they want docs, run a command like:
    easy_install --get-docs enthought.traits
where easy_install would then introspect the enthought.traits egg and 
figure out how to retrieve the docs and install them into ../python/docs.


If we found time to work on implementing something, is there a 
preference for which path we should pursue?

-- Dave