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

[Nick Coghlan]

On Mon, May 21, 2012 at 3:47 PM, Terry Reedy <tjreedy at udel.edu> wrote:
> 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.

Please, no - proliferating subdomains can quickly get confusing and
hard to remember. It makes sense up to a point (e.g. separating out
the docs from everything else on python.org), but having multiple docs
subdomains is completely unnecessary when we already have directory
based versioning.

Namespaces are a great idea, let's do more of those :)

> 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.

Having "http://docs.python.org/latest" refer to Python 3.x would
remove the "second class citizen" status, as well as providing a clear
indication right in the URL that docs.python.org contains more content
than just the latest version of the docs. The unqualified URLs could
then become redirects to "latest" after a suitable migration period
with a notification and a link to the 2.7 version specific docs on
each page.

For example, at the release of 3.3, each page of the default docs on
the website could be updated with a note like the following:

"The default documentation pages will be switching to the Python 3
series in February 2012, 6 months after the release of Python 3.3. The
permanent link for the 2.7 version of this page is: <URL with the
"2.7" directory entry>"

> 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.

Right, and switching the default docs without a suitable notice period
would be a great way to generate confusion. Migrating to a "latest"
URL has no such negative impact:
- the new URLs become available immediately for those that want to use them
- the old URLs can be converted to 301 redirects after a suitable warning period

> 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.

I think "http://docs.python.org/2.7" is fine as the long term home for
the final version of the Python 2 documentation (it also has the
virtue of already existing).

>> 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.

That's what the Django widget does. I'm not talking about their search
form - I'm talking about the floating CSS box that appears in the
bottom right of each page and stays there as you scroll down. If you
click on it, the list of available documentation versions appears,
with direct links to the corresponding page in the other versions.

It has several attractive features:
- always present, even when you scroll down on a long page
- unobtrusive when you don't need it (only displays current version by
default, have to click it to get the list of all versions)
- direct links to the corresponding page in other versions

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia