[Python-ideas] docs.python.org

[Nick Coghlan]

On Sat, Oct 27, 2012 at 8:54 PM, M.-A. Lemburg <mal at egenix.com> wrote:
> On 27.10.2012 08:22, Nick Coghlan wrote:
>> So that's my concrete proposal:
>> 1. We pick a date (June next year sounds about right)
>> 2. We pick a stable URL prefix for the Python 2 docs (I vote "/2.x/")
>
> Why "/2.x/" and not just "/2/" ?

I find the /2/ vs /3/ too easy to miss in the middle of a full URL,
whereas I find the extra space to the right of the number in /2.x/ vs
/3.x/ makes them easier to separate.

However, in writing up the PEP, I discovered it was annoyingly
ambiguous whether "/2.x/" specifically meant that URL, or whether it
meant "/2.7/" and friends, so I switched to the shorter form.

>> 3. We start redirecting affected pages immediately
>
> I think we should do the same for all Python 3 resources, i.e.
> have "/library/os.html" redirect to "/3/library/os.html" so that
> we don't run into the same problem again in the future.

In writing up the PEP, I rediscovered an old proposal of mine to avoid
breaking deep links by simply do a "documented deprecation" of
unqualified deep links, but otherwise leaving them pointing to Python
2. Only the default landing page would be switched to Python 3.

Since that approach avoids a *lot* of issues, that's what I ended writing up.

>> 4. We add a notice like the one above to the home page of the 2.7
>> docs, announce it on the PSF blog, announce it far and wide
>
> We also need a solution for URLs that exist for Python 2, but
> not for Python 3. Those should be redirected to the Python 2
> resource automatically, e.g. URLs pointing to the Python 2 modules
> that were renamed in Python 3.
>
> BTW: Will you write up a PEP for this ?

Committed as PEP 430, should show up
http://www.python.org/dev/peps/pep-0430 before too long.

Cheers,
Nick.

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