Documentation is spread out all over the place

[dstufft]

The documentation for all the various pieces a user is expected to know is spread out all over the place. There should be one central location where users can go to learn about everything.

This is probably solved by the packaging guide.

[qwcode]

Yes, the Packaging Guide aims to be to the de facto gateway that can pull it all together, but the various projects still need good docs themselves (pip, setuptools, virtualenv, distutils), that are modernized and conscious of their current place in the story. Currently the distutils and setuptools docs are very unconscious and outdated. That's one of my biggest concerns at the moment, is to improve those.

[ncoghlan]

/cc @jaraco

Part of PEP 453 is to start using the CPython docs as a pointer and official blessing of the packaging user guide, which should help with the "What's authoritative?" problem. There'll still be a bit of bouncing around until user's get to where they need to go, but at least we'll be providing a map rather than saying "Here's a search engine: go!"

One specific problem at the moment is that the distribute docs still exist and aren't being updated, rather than merely serving as a pointer to the setuptools docs: http://pythonhosted.org/distribute/

Not wanting to break deep links is a legitimate concern, but there needs to be something more prominent telling people that distribute is deprecated. Perhaps a Sphinx warning at the top of every page, with a pointer over to the setuptools docs?

[qwcode]

thinking more radically here, maybe it is worth considering one cross-project set of documentation for pip, setuptools, and virtualenv. it would be much easier to put together one story (without duplication), with the right things emphasized consistently. I.e. literally, pip, setuptools, and virtualenv stop maintaining their own docs. maybe too crazy?

[dstufft]

I think they should still have their own documentation, but I think that the guide should be use all of the recommended tooling at a basic level.

[jaraco]

I remember seeing a ticket in distribute to this effect. I want to rapidly start tearing down the distribute infrastructure.

[jaraco]

I've just uploaded new versions of the distribute docs which removes all of the pages and replaces only the home page with a link to Setuptools.

[tomprince]

I think they should still have their own documentation, but I think that the guide should be use all of the recommended tooling at a basic level.

They should certainly all have complete documentation. But that could be a single combined document.

[qwcode]

@jaraco do you have the permissions to do similar with the old "Hitchhiker's Guide to Packaging" http://guide.python-distribute.org/

[jaraco]

I don't have access to that site. I believe only Tarek does. I do have a login on the server, but that account only has access to the python-distribute.org site (guide is a separate one). I do have read access, which pointed me to the hg repo that backs the site. The site suggests that many might have commit access, but I don't know the deployment routine.

I think the best thing we can do for that site is send a pull request (or commit the changes) and ask for it to be deployed.

[brainwane]

Now that https://packaging.python.org/ exists and is generally understood to be the home for Python packaging documentation, can we close this issue?

[ncoghlan]

Aye, we've resolved this now. There are still a lot of gaps to fill in, but we at least know where the content is expected to live :)