classification
Title: Add a version switcher to python docs site
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.4, Python 3.3, Python 3.2, Python 2.7
process
Status: closed Resolution: duplicate
Dependencies: Superseder: documentation pages should link to other versions of the same page
View: 8040
Assigned To: docs@python Nosy List: chris.jerdonek, docs@python, eric.araujo, ezio.melotti, georg.brandl, loewis, r.david.murray, rhettinger, yselivanov
Priority: normal Keywords: patch

Created on 2012-10-26 17:34 by yselivanov, last changed 2012-10-26 20:15 by loewis. This issue is now closed.

Files
File name Uploaded Description Edit
py3_version_switch.patch yselivanov, 2012-10-26 17:34 review
Messages (13)
msg173864 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2012-10-26 17:34
This patch adds a dropdown to python documentation top toolbar:
https://dl.dropbox.com/u/21052/python/p3_doc_dd.png

This patch version is for python 3.3 & 3.4 docs theme, but I can quickly make patches for 3.2-style and below.

JavaScript that monitors dropdown events is smart enough to:

1) Redirect users to the same documentation section, i.e. if the user is on 'atexit' module doc page for 3.3, and decides to switch to '2.7', he'll see 'atexit' module doc page for 2.7

2) Before making a redirect, is checks that the doc page exists for the selected python version, and if not, then it simply redirects to 'http://docs.python.org/{version}'

3) Users with JS disabled will see a plain-text current version (no drop down)
msg173865 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-10-26 17:37
Thanks for the patch.

What happens if the module doesn't exist in a previous version or if it has a different name?

It's probably not necessary to include all those versions.
msg173866 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2012-10-26 17:39
> What happens if the module doesn't exist in a previous version or if it has a different name?

As I said in the first message:

"""
2) Before making a redirect, is checks that the doc page exists for the selected python version, and if not, then it simply redirects to 'http://docs.python.org/{version}'
"""

That's the most sane method I can imagine.
msg173868 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-10-26 17:56
I left a review on rietveld.

FWIW we discussed this already somewhere, and IIRC the two main issues were:
1) mapping new/renamed/delete files between versions;
2) making this work while building the docs locally;

Redirecting to 'http://docs.python.org/{version}' might be an acceptable solution for 1) if we don't want to keep lists of module names.
Regarding 2) it depends on the local directory layout, so it would need to be configurable.

These are just further enhancements though, I think it would be good to have something similar even if it doesn't cover all the possible cases.
msg173869 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-10-26 18:00
See #8040.
msg173870 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2012-10-26 18:03
> 1) mapping new/renamed/delete files between versions;
I think that this dropdown is mostly like to be used to switch between somewhat recent python versions, like '3.2' -> '3.3', '2.7' -> '3.3', and not between '2.4' -> '3.4'

And most of the internet links point to plain 'docs.python.org', without version at all.

> 2) making this work while building the docs locally;
I think we need to make this JS dropdown to be off by default; so local users won't notice a thing.
msg173871 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-10-26 18:09
> I think that this dropdown is mostly like to be used to switch between 
> somewhat recent python versions, like '3.2' -> '3.3', '2.7' -> '3.3',
> and not between '2.4' -> '3.4'

I mostly want to switch between 2.x and 3.x, and several modules got renamed between these versions.  There are also new modules on each release (5 new ones in 3.3).


> I think we need to make this JS dropdown to be off by default;
> so local users won't notice a thing.

Even better would be to make it work -- while fixing the docs I often have to apply a patch on each version and then check that it works.  If that's not implemented, disabling it sounds OK.  By now I'm used to just change the URLs (I do the same even on docs.python.org), but it would be a nice addition.
These are just further improvements though, they don't necessarily prevent the current patch to be accepted.
msg173872 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2012-10-26 18:16
> I mostly want to switch between 2.x and 3.x, and several modules got renamed between these versions.  There are also new modules on each release (5 new ones in 3.3).

To make that work we'll need to have a modules mapping between 2nd and 3rd versions.  It will also make URL parsing/changing logic more complicated and error prone...
msg173875 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2012-10-26 18:18
Eric,

I'm not sure what we should do with #8040.  I searched for the existing issue before creating a new one, but obviously failed.  Should we just close #8040 and point it to #16331?
msg173876 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-10-26 18:19
Typically we close the newer issue as duplicate of the existing one, unless the new has much more discussion or patches.  I would close this one.

About renamed modules: there’s a mapping in lib2to3 that contains the info.
msg173877 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2012-10-26 18:24
Eric, Ezio,

This one has a patch attached with a relevant discussion & review, so I'd close #8040.

But if you guys decide to close this one and switch to #8040 - i'm fine.
msg173884 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-26 20:10
I recommend closing this as a duplicate.
msg173885 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2012-10-26 20:14
yselivanov: please resubmit the patch to the original issue.
History
Date User Action Args
2012-10-26 20:15:12loewissetsuperseder: documentation pages should link to other versions of the same page
2012-10-26 20:14:41loewissetstatus: open -> closed

nosy: + loewis
messages: + msg173885

resolution: duplicate
2012-10-26 20:10:58chris.jerdoneksetnosy: + chris.jerdonek
messages: + msg173884
2012-10-26 18:24:12yselivanovsetmessages: + msg173877
2012-10-26 18:19:48eric.araujosetmessages: + msg173876
2012-10-26 18:18:00yselivanovsetmessages: + msg173875
2012-10-26 18:16:00yselivanovsetmessages: + msg173872
2012-10-26 18:09:55ezio.melottisetmessages: + msg173871
2012-10-26 18:03:24yselivanovsetmessages: + msg173870
2012-10-26 18:00:56ezio.melottisetmessages: + msg173869
2012-10-26 17:56:56ezio.melottisetnosy: + eric.araujo, r.david.murray
messages: + msg173868
2012-10-26 17:39:12yselivanovsetmessages: + msg173866
2012-10-26 17:37:25ezio.melottisetversions: + Python 2.7, - Python 3.1
nosy: + ezio.melotti

messages: + msg173865

stage: patch review
2012-10-26 17:34:31yselivanovsettype: enhancement
2012-10-26 17:34:20yselivanovcreate