Docs for the packaging module
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
Hi, Looks like nobody cares enough about the packaging docs :) If there is no feedback, here’s what I propose to do: - Add new Doc/library/packaging* files (library reference for developers of packaging tools) - Add new packaging-based “Installing Python Projects” to Doc/install, replacing old distutils docs - Add new packaging-based “Distributing Python Projects” Doc/packaging, replacing old distutils docs (+ link to it from the main HTML page instead of linking to Doc/distutils) For users needing the legacy distutils docs in 3.3, I would move the older distutils Doc/install/index.rst to Doc/distutils/install.rst, and add a link to Doc/distutils in Doc/library/distutils (because the main page would no longer link to Doc/distutils). Regards
2011/6/1 Éric Araujo <merwok@netwok.org>:
Hi,
Looks like nobody cares enough about the packaging docs :)
Perhaps your solutions are perfect already. :)
If there is no feedback, here’s what I propose to do:
- Add new Doc/library/packaging* files (library reference for developers of packaging tools)
- Add new packaging-based “Installing Python Projects” to Doc/install, replacing old distutils docs
- Add new packaging-based “Distributing Python Projects” Doc/packaging, replacing old distutils docs (+ link to it from the main HTML page instead of linking to Doc/distutils)
For users needing the legacy distutils docs in 3.3, I would move the older distutils Doc/install/index.rst to Doc/distutils/install.rst, and add a link to Doc/distutils in Doc/library/distutils (because the main page would no longer link to Doc/distutils).
Or we could just delete them and have people look at docs for old versions of Python. -- Regards, Benjamin
Hi Benjamin,
For users needing the legacy distutils docs in 3.3, I would move the older distutils Doc/install/index.rst to Doc/distutils/install.rst, and add a link to Doc/distutils in Doc/library/distutils (because the main page would no longer link to Doc/distutils).
Or we could just delete them and have people look at docs for old versions of Python.
Given that we haven’t removed the code, I would prefer to keep the doc too. Tarek has given me the greenlight, so I will commit the new docs momentarily. Cheers
I do care :) Looks fine Please push, as we can always change and fix things afterwards in the tip before 3.3 is out. Le 1 juin 2011 19:38, "Éric Araujo" <merwok@netwok.org> a écrit :
Hi,
Looks like nobody cares enough about the packaging docs :) If there is no feedback, here’s what I propose to do:
- Add new Doc/library/packaging* files (library reference for developers of packaging tools)
- Add new packaging-based “Installing Python Projects” to Doc/install, replacing old distutils docs
- Add new packaging-based “Distributing Python Projects” Doc/packaging, replacing old distutils docs (+ link to it from the main HTML page instead of linking to Doc/distutils)
For users needing the legacy distutils docs in 3.3, I would move the older distutils Doc/install/index.rst to Doc/distutils/install.rst, and add a link to Doc/distutils in Doc/library/distutils (because the main page would no longer link to Doc/distutils).
Regards _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/ziade.tarek%40gmail.com
On Wed, 01 Jun 2011 19:15:54 +0200, <merwok@netwok.org> wrote:
Looks like nobody cares enough about the packaging docs :) If there is no feedback, here’s what I propose to do:
I think you should go ahead and make your changes, and then we'll be able to see what it really looks like and decide if anything ought to be tweaked. -- R. David Murray http://www.bitdance.com
participants (4)
-
Benjamin Peterson -
R. David Murray -
Tarek Ziadé -
Éric Araujo