[Distutils] layout and setup.py for packaging documentation

[Tarek Ziadé]

On Mon, Mar 1, 2010 at 1:08 PM, Jean Daniel <jeandaniel.browne at gmail.com> wrote:
>> As a matter of fact, we've worked on this during the sprints, and are
>> preparing a proposal
>> that will let people define a place for doc (and other stuff) and let
>> the OS packager decide where
>> it lands (with defaults per OS).
>
> I'll read the proposal. I wonder how it is possible to layout a source
> tarball with hints to the OS packager on how to do the right thing.
> From what I have seen, there is no really specification or convention
> for tagging a directory in a source tarball as 'doc' in a language
> agnostic and OS agnostic way.

This is done by describing the content of your source tarball in a
much detailed way than what we have today.

We worked with Fedora+Ubunte ppl on this, and started to specify those
things here:

http://hg.python.org/distutils2/file/cdf2da431e2b/docs/design/wiki.rst

This is a 3 days work during the sprint with 4/5 ppl involved. It also
contains elements from previous works on the topic.

It's a work in progress but you can read it to get an idea on where we
are going.

To roughly summarize the idea, each platform (a platform is a
different os.name value) will have default paths for each location of
a pseudo-FHS that goes further than Python installations locations. So
we include things such as configuration files location, or help files
location, etc...  Then each OS packagers will be able to change these
paths globally from a configuration file. Windows will have dummy
locations.

You, as a developer, will just have to point the location on your
project's tree and tell what kind of file it is, then use an API in
your code to read back the file (wherever it finally lands).

We are working on this proposal to be included in PEP 376, then we
will propose it here at distutils-SIG, for a
round of feedback, rework, etc.

The goal is to see it ready within 5 weeks, (before Python2.7 first
beta). It's a hard goal but if we manage to reach it, it means that I
will be able to change Python's sysconfig module for 2.7 (+pkutil
APIs), and provide a backport of it in distutils2 for people to start
using it.

>
> Does anyone know if the good people form Perl and Ruby have came up
> with a good solution?

As far as I know, there's no such detailed information on Ruby or Perl
land, but I am not an expert -- I just lurked into those worlds.

I do believe that if we finish that proposal and include it, Python
will be the most advanced one on this particular topic compared to
Ruby or Perl.

Regards
Tarek

-- 
Tarek Ziadé | http://ziade.org