On Sun, Feb 28, 2010 at 11:39 PM, Michael Foord wrote:

On 28 February 2010 22:14, P.J. Eby wrote:

...

At 10:03 PM 2/28/2010 +0100, Jean Daniel wrote:

...

Can this be simpler?

Yes.  Don't install docs with your package.  People who want them installed locally can just download your source install or use easy_install -e.

Also, if your module is popular enough that people make Linux system packages for it, they will make sure the docs get put in a blessed install location.  Python doesn't currently have a blessed install location for documentation, though perhaps it *should* have one in distutils2.

How to include documentation in a package is a common question, so it would be great if distutils2 could deal with this issue.

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 post if there when its ready, hopefully soon Tarek

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.

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

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 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@python.org http://mail.python.org/mailman/listinfo/distutils-sig

On Mon, Mar 1, 2010 at 5:52 PM, Sridhar Ratnakumar wrote:

On 2010-03-01, at 8:44 AM, Sridhar Ratnakumar wrote:

...

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?

.. and/or make a single-container (eg: CHM[1]) out of it. I guess this feature could be made optional, so developers can include simple docs without having to worry about any mandatory standard, and we could contribute a Sphinx patch to automatically produce toc.xml.

-srid

*** [1] ActivePython already includes extra docs (tutorials, peps. etc..) in a CHM file along with the Python docs

We didn't make any assumption on the documentation files format. But now that they will be described, you could create a distutils2 command that generates toc.xml on the fly by reading the list of doc files in the project (build_msn_doc?) Another idea that come in my mind also for structurized doc is to use skeletons when the project is created in the first place. (that's also a good way to standardize how the community creates its packages) Sean R. worked on a command called mkpkg that can be used to generate a distutlils2-based project. It asks a few questions then creates a setup.py file for you. Maybe it could be extended to build a pre-generated Sphinx doc structure, or a CHM-like one. The difficulty is to provide something that can evolve on its own. Plugins maybe ? Last, I think that this work could be reunited with the work done in Distribute's build_doc/upload_doc commands. Regards Tarek -- Tarek Ziadé | http://ziade.org