[Python-Dev] docs.python.org pointing to Python 3 by default? (original) (raw)

Terry Reedy tjreedy at udel.edu
Mon May 21 07:47:50 CEST 2012

On 5/21/2012 12:28 AM, Nick Coghlan wrote:

On Mon, May 21, 2012 at 11:23 AM, Guido van Rossum<guido at python.org> wrote:

I suggest that we add a separate (virtual) subdomain, e.g. docs3.python.org.

I was about to post the exact same idea.

docs.python.org/py3k is a bit obscure and buried and makes Python 3.x look a bit like a second-class citizen on the site. It has previously been our policy that each new production-ready release takes 'pride of place' at docs.python.org. Not doing so even with 3.3, and doing nothing else, could be taken as implying that we lack full confidence in the release.

On the other hand, I am sympathetic to Raymond's and Nick's points that switching might seem too much 'in their faces' for Py 2 users, especially those who do not have or use an offline help file as their everyday reference. I want Python 3 to get equal billing, but not to generate reaction against it.

I also suggest docs2.python.org as the permanent home for latest python 2 docs for as long as it seems sensible (probably a decade at least). Make that operable now and suggest on the front page of docs.python.org that py2 users switch before 3.4.

Rather than a new subdomain, I'd prefer to see a discreet "documentation version" CSS widget, similar to that used in the Django docs (see https://docs.djangoproject.com/en/1.4/) that indicated the current displayed version and provided quick links to the 2.7 docs, the stable 3.x docs and the development docs.

Each page of our docs say "Python 3.3.0a3 Documentation", or the equivalent, at the top. So we already have that covered. The drop-down version selection box on the django page seems to only apply to searches. Merely selecting a different version does not trigger anything.

What might be useful is to have the 'Other versions' links on the left margin of every page, not just the front page, but have them link to the corresponding page of the other docs (if there is one, and non-trivial I expect). For someone trying to write combined 2/3 code, or merely to learn the other version, I would think it useful to be able to jump to the corresponding page for the other version.

-- Terry Jan Reedy

More information about the Python-Dev mailing list