homepage

Currently, trying to use a web search engine to find something in the Python docs often returns the documentation for only one version of Python. Something a very old version like 2.3.
It would be nice if the documentation pages on docs.python.org included links to older and later versions of the same documentation page, if one exists. That would make it much easier to navigate to the desired version of a page. The extra links could be placed on the sidebar on the left side, perhaps below the Quick Search box.
Additionally, it might help search engines find and index the documentation for the other versions.
Microsoft does this for their .NET documentation and it's very handy (e.g., http://msdn.microsoft.com/en-us/library/system.windows.forms.control.aspx)

It think it's also extremely difficult to implement, since the switchover to a new documentation generator. Contributions are welcome.

The link does not currently work.
I think this effectively impossible for volunteers. Microsoft has 1000s of paid employees. Chapter and Sections numbers do not match from version to version.
How many other versions would you link to? Multiple links could get a bit ugly.
What might be done is to put one permanent link to "All doc versions" on the sidebar.

I think I've already discussed this with Georg a while ago and we ended up adding the links on the left sidebar in http://docs.python.org/.
IIRC there's no easy way to find the same document in another version of the doc, not even now with Sphinx.
I think this can be closed, unless Georg disagrees.

On Sat, Jul 10, 2010 at 1:56 AM, Terry J. Reedy <report@bugs.python.org>wrote:
> I think this effectively impossible for volunteers. Microsoft has 1000s of
> paid employees. Chapter and Sections numbers do not match from version to
> version.
>
We don't need to match numbers, we just need to match links, which in 99% of
all cases follow a regular pattern:
For example:
http://docs.python.org/py3k/library/fractions.html
http://docs.python.org/library/fractions.html
http://docs.python.org/release/2.6.5/library/fractions.html
It's pretty easy to generate the links to the corresponding pages. The
trickier part is testing that the link is valid when building the pages.
In an ideal universe, there would be a way to manually specify when a page
has been renamed (e.g., _winreg -> winreg), but even if those links were
missing it would still be quite useful (IMO, of course).
How many other versions would you link to? Multiple links could get a bit
> ugly.
>
The same number as currently listed in the sidebar on the index page.

On Sat, Jul 10, 2010 at 2:12 AM, Ezio Melotti <report@bugs.python.org>wrote:
> I think I've already discussed this with Georg a while ago and we ended up
> adding the links on the left sidebar in http://docs.python.org/.
> IIRC there's no easy way to find the same document in another version of
> the doc, not even now with Sphinx.
> I think this can be closed, unless Georg disagrees.
When I opened this issue originally, I hadn't learned Sphinx yet and
couldn't propose a solution. Since then I've started using Sphinx and have
a much better idea of what it can and cannot do.
It would require a new Sphinx extension, but it need not be a complex one.
Inside sidebartoc:
<h3>Docs for other versions</h3>
<ul>
(call extension module)
</ul>
The extension module would use a global directory (outside of a particular
version's Sphinx build) to keep track of which versions had generated the
same page. The builds would have to be run twice, once to produce all of
the information and once to include it. Alternately, they could be run once
if it's acceptable to use Apache Server-Side-Includes (SSI).
If you want to assign the issue to me and leave it open, that would be fine
with me. I can't promise to get to it soon, but I'm willing to work on it
eventually.

All yours. Good luck. As usual, no guarantees on acceptance of any particular patch.
I am marking this for 3.2 because that is where new *code* will go and that is also the doc set you should experiment with. That is not to say that new code, once approved, cannot be applied to past doc sets.

If you want to work on this you should also consider that the URLs used on docs.python.org don't necessary match the directory structure present when building the doc locally. For example here it would be:
.../py3k/library/fractions.html
.../release31-maint/library/fractions.html
.../release27-maint/library/fractions.html
.../release26-maint/library/fractions.html
This could be addressed with a config file that is not kept under version control (and possibly with default values used when this file is not present).

You might want to check out what Django does, as they have the working well. http://docs.djangoproject.com/en/dev/ 

On Tue, Dec 14, 2010 at 7:22 PM, Ezio Melotti <report@bugs.python.org> wrote:
> If you want to work on this you should also consider that the URLs used on docs.python.org don't necessary match the directory structure present when building the doc locally. For example here it would be:
> .../py3k/library/fractions.html
> .../release31-maint/library/fractions.html
> .../release27-maint/library/fractions.html
> .../release26-maint/library/fractions.html
Will this directory structure change as part of the hg migration?

No, because with Subversion or Mercurial you’re free to clone/checkout any branch in a directory with an arbitrary name. For the py3k branch, Ezio’s checkout is named py3k but mine is 3.2, there is no way to put knowledge about that in the doc itself.

> If you want to work on this you should also consider that the URLs used on docs.python.org don't necessary
> match the directory structure present when building the doc locally.
I think this is irrelevant; this feature is intended for the web site, not for developers building the docs.

As I said on #16331, it would be nice to have it, but it shouldn't block a patch that works for the website only (having it there is still better than not having it at all).
What I meant to say is that taking this into account while writing the code is a good idea, and having configurable paths might also turn out to be useful in case we change the configuration of docs.python.org.

[on yselivanov's patch]
I think the menu should drop versions that are not maintained anymore, i.e. anything older than 2.5 (including). If that sounds too harsh, a single item "older" could be added that always navigates to the version selection page.
With that, navigating to non-existing pages becomes mostly a non-issue, except for the renaming from 2.x to 3.x.
If the list is trimmed in that way, I propose to add the links to the side menu, rather than as a separate drop-down menu.

Eric, Ezio,
I'd like to make the version dropdown to be configurable. The question is--I can add an option (set to False by default) to conf.py. Will you have a way to override it on the 'docs.python.org'?

A few comments:
* If the issue with patch is closed as duplicate, the patch should be attached to the superseder.
* The patch looks awfully long for such a simple option list. (e.g., get_version() is just lambda x: x[:3], no need for a function to do that.)
* Keep in mind that you can't easily support 2.5 and down anyway, since their URLs are completely different. I call YAGNI on including anything older than 2.6.
* Please make it configurable, as indicated. You can add an option recognized by Sphinx in Doc/tools/sphinxext/pyspecific.py, with app.add_config_value. I will then set it properly in the script that rebuilds the docs on docs.python.org.
That said, the result looks nice. If we can work out the specifics, +1 for something like it.

> If the issue with patch is closed as duplicate, the patch should be attached to the superseder.
Attached now. Although, please don't use it. I'll upload an updated version soon.
> The patch looks awfully long for such a simple option list. (e.g., get_version() is just lambda x: x[:3], no need for a function to do that.)
Well, I've tried to make it readable. I can uglify it, but it won't save too much. Right now it's about ~2.5kb.
> Please make it configurable, as indicated. You can add an option recognized by Sphinx in Doc/tools/sphinxext/pyspecific.py, with app.add_config_value. I will then set it properly in the script that rebuilds the docs on docs.python.org.
Is it OK if I make it configurable via theme config property?
And if not - how to make a config option declared via 'app.add_config_value' accessible in templates?

Attaching a new patch, with all previous issues resolved.
Version dropdown can be enabled by the new 'pydoc_versionswitcher' config property (False by default).
Please review and test (I've done lots of testing by injecting the JS on live python docs site, but maybe missed something.)

Adding 'py2_version_switch.patch' patch. Applies on 2.7

Adding 'py3_2_version_switch.patch'. Applies on 3.2
Both patches (for 2.7 & 3.2) are almost the same as the original patch. Conflicts were trivial.

And 'py3_version_switch.2.patch' is for 3.3/master.

> Both patches (for 2.7 & 3.2) are almost the same as the original patch. Conflicts were trivial.
For future reference, it's okay (and perhaps preferable) to upload a patch just for the default branch when no substantive changes are needed for other branches. This is especially true early in the review process when multiple iterations may be uploaded.

Found a bug: documentation pages have two toolbars - top and bottom, and as I hadn't noticed the latter, I used a placeholder with #id. This is now fixed.
I'm attaching a new version of patch: 'py3_version_switch.3.patch'.
I also have updated patches for 3.2 & 2.7, so if this iteration is OK, I'll upload them as well.

> For future reference, it's okay (and perhaps preferable) to upload a
> patch just for the default branch when no substantive changes are
> needed for other branches. This is especially true early in the
> review process when multiple iterations may be uploaded.
Definitely preferable.

Attaching a simplified version of the patch.

> Attaching a simplified version of the patch.
I'm OK, but you actually reduced the functionality with saving those 500 bytes.
In 'py3_version_switch.3.patch', JS sets the current selected option text to show the the *full* release number. I.e. if you are on the 3.3 doc site, 3.3.0 will be selected and shown in the dropdown (and 3.4.0a1 for /dev/ etc) I think that was a useful thing.

My bad, you're right. Next try attached.

Georg,
Are you sure you've attached the right one? I don't see a change in the version_switch.js...

Now it should be the right one.

Looks good, let's commit it? ;)

Maybe it's a good idea to modify `url_re` from
/\.org\/(py3k|dev|((release\/)?\d\.\d[\w\d\.]*))\//
to
/\.org\/(\d|py3k|dev|((release\/)?\d\.\d[\w\d\.]*))\//
To be prepared for PEP 430.

New changeset 006f9ade82f2 by Ezio Melotti in branch '2.7':
#8040: add a version switcher to the documentation. Patch by Yury Selivanov.
http://hg.python.org/cpython/rev/006f9ade82f2
New changeset 35a2a0e166d0 by Ezio Melotti in branch '3.2':
#8040: add a version switcher to the documentation. Patch by Yury Selivanov.
http://hg.python.org/cpython/rev/35a2a0e166d0
New changeset 9505a34b4484 by Ezio Melotti in branch '3.3':
#8040: merge with 3.2.
http://hg.python.org/cpython/rev/9505a34b4484
New changeset 9552d8b90683 by Ezio Melotti in branch 'default':
#8040: merge with 3.3.
http://hg.python.org/cpython/rev/9552d8b90683 

New changeset c3adbe20bb4b by Ezio Melotti in branch '2.7':
#8040: enable the versionswitcher for the autobuild-dev target.
http://hg.python.org/cpython/rev/c3adbe20bb4b
New changeset 740be7346c92 by Ezio Melotti in branch '3.2':
#8040: enable the versionswitcher for the autobuild-dev target.
http://hg.python.org/cpython/rev/740be7346c92
New changeset 5c30f8fdd896 by Ezio Melotti in branch '3.3':
#8040: merge with 3.2.
http://hg.python.org/cpython/rev/5c30f8fdd896
New changeset 75bff8c947d0 by Ezio Melotti in branch 'default':
#8040: merge with 3.3.
http://hg.python.org/cpython/rev/75bff8c947d0 

Ezio,
Georg's modification introduced one more bug:
1. Documentation for py2 seems to be missing DOCUMENTATION_OPTIONS.RELEASE 
2. DOCUMENTATION_OPTIONS.VERSION is in a wrong format for the rest of the script, i.e. 3.3.0 and not 3.3. Before, in my version there was a code that worked around this.
Please apply attached patch that fixes all that.

New changeset 7ca30af90c11 by Ezio Melotti in branch '2.7':
#8040: fix the version.
http://hg.python.org/cpython/rev/7ca30af90c11
New changeset 36a35b86e3b0 by Ezio Melotti in branch '3.2':
#8040: fix the version.
http://hg.python.org/cpython/rev/36a35b86e3b0
New changeset 7cabdb58fb23 by Ezio Melotti in branch '3.3':
#8040: merge with 3.2.
http://hg.python.org/cpython/rev/7cabdb58fb23
New changeset 9a97b6d2e24a by Ezio Melotti in branch 'default':
#8040: merge with 3.3.
http://hg.python.org/cpython/rev/9a97b6d2e24a 

Indeed RELEASE is not defined anywhere. I was confusing JS variables and Jinja template variables: DOCUMENTATION_OPTIONS.VERSION is in fact what Sphinx calls "release".
So the fix should be to use VERSION as release and VERSION[:3] as version. Thanks for catching that.

I think we should also apply patch for 2.6, right?

And last bit - are you sure we shouldn't add the switch for 2.5?

And if you guys can - please re-run the docs generation script manually... As it's showing an incorrect version everywhere.
Thanks!

2.5 is neither supported anymore, nor should we make it look like it is :)

It seems that the docs site has old jquery - 1.4, and current JS script uses $.get, which got support for 'error' callbacks only in 1.5
So right now, if a URL doesn't exist for the version the user is about to switch to, it just fails with a JS error.
I'm attaching one more (hopefully last!) patch to fix that.
Thanks.

(I'd fix it myself if I could ;)

New changeset 4a17784f2fee by Georg Brandl in branch '2.6':
#8040: port versionswitcher patch to 2.6.
http://hg.python.org/cpython/rev/4a17784f2fee 

New changeset e02d49db3f5b by Georg Brandl in branch '3.2':
#8040: fix jQuery incompatibility
http://hg.python.org/cpython/rev/e02d49db3f5b 

OK, with the latest patch it seems to work fine for me. I've run the autobuild for 2.7/3.3/3.4 and put custom built versions of 2.6/3.2 on dinsdale, so everything should look and work fine.
I've also added todo items to PEP 101, in order to make sure the version list in version_switcher.js is properly updated on new feature versions.

Thanks Yury for the work!

New changeset f306777e0b6d by Ezio Melotti in branch 'default':
#17175: remove outdated paragraph about issue #8040 from PEP 430. Patch by Tshepang Lekhonkhobe.
http://hg.python.org/peps/rev/f306777e0b6d