[Python-Dev] Docs for the packaging module

[Éric Araujo]

 Hi,

 The docs were not added alongside the code when packaging was merged
 back into CPython because they were not in a shape conforming with the
 rest of the docs.  I’d like your input on layout so that I can fix this
 ASAP and merge the docs.  (They would still require a lot of additions,
 fixes and improvements after that, but at least they’d be in the repo.)

 The easiest part is the library documentation, i.e. the docs for
 developers of packaging-related tools that want to use for example
 packaging.version or packaging.metadata to do their own stuff.  These
 documents should go into Doc/library/packaging.*, I think this is a
 no-brainer.  (Distutils has only a stub here, its API docs is mixed 
 with
 its usage docs.)

 There is a guide for end-users, which contains an outdated copy of the
 old “Installing Python Modules” and a few documents about the new
 pysetup script (superseder of setup.py scripts), which are not
 integrated with the first document.  I think those should supersede the
 existing distutils-based Doc/install tree.  We want to advertise 
 pysetup
 and packaging as the way of gettting modules in 3.3.  A question
 remains: is it worthwhile to keep the old document somewhere?

 Last but not least, the doc for authors wanting to package and
 distribute their project (“Distributing Python Modules”, 
 Doc/distutils).
  I think we should not overwrite this directory, because the directory
 name is tied to distutils and because there will be users needing that
 documentation (distutils is not removed).  So, is it okay to create a
 new Doc/packaging directory and change the link on the docs front page
 from distutils to packaging?
 (Technical question: I think I’ll get a complaint from Sphinx that
 distutils is not included in any toctree; I’ll try adding a toctree 
 from
 library/distutils to distutils/index and see if that works.)

 Thanks for reading