[Distutils] layout and setup.py for packaging documentation

[Sridhar Ratnakumar]

Ah, very nice!

This was one of the things I wanted to discuss in the sprints. I've been mentioning this idea internally as well. Having documentation standards would ultimately benefit the user who could thus have a central place on his computer to browse documentation for installed Python packages which packages are installed via easy_install/pip/enstaller/PyPM/etc...

I'm not sure how far this was discussed in the sprints. Is the documentation directory expected to contain files in certain format - for example, with a file describing the Table-of-Contents (toc.xml) that would then be used to render MSDN like doc tree?

-srid

On 2010-03-01, at 4:52 AM, Tarek Ziadé wrote:

> 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
> _______________________________________________
> Distutils-SIG maillist  -  Distutils-SIG at python.org
> http://mail.python.org/mailman/listinfo/distutils-sig