[Python-Dev] docs.python.org pointing to Python 3 by default?

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