documentation pages should link to other versions of the same page

[stutzbach]

BPO	8040
Nosy	@loewis, @birkenfeld, @terryjreedy, @ezio-melotti, @merwok, @cjerdonek, @1st1
Files	py3_version_switch.patch py3_version_switch.2.patch py2_version_switch.patch: (outdated) py3_2_version_switch.patch: (outdated) py3_version_switch.3.patch versionswitcher.4.patch versionswitcher.5.patch switcher_js.patch switcher_js.ajax.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2012-10-28.07:30:40.983>
created_at = <Date 2010-03-02.15:30:44.502>
labels = ['type-feature', 'docs']
title = 'documentation pages should link to other versions of the same page'
updated_at = <Date 2013-02-15.20:04:38.956>
user = 'https://bugs.python.org/stutzbach'

bugs.python.org fields:

activity = <Date 2013-02-15.20:04:38.956>
actor = 'python-dev'
assignee = 'stutzbach'
closed = True
closed_date = <Date 2012-10-28.07:30:40.983>
closer = 'georg.brandl'
components = ['Documentation']
creation = <Date 2010-03-02.15:30:44.502>
creator = 'stutzbach'
dependencies = []
files = ['27736', '27737', '27738', '27739', '27742', '27743', '27746', '27751', '27754']
hgrepos = []
issue_num = 8040
keywords = ['patch']
message_count = 47.0
messages = ['100297', '100311', '109826', '109827', '109860', '109864', '109909', '124004', '124009', '124151', '124153', '173874', '173878', '173886', '173887', '173890', '173894', '173895', '173898', '173899', '173900', '173903', '173904', '173911', '173912', '173926', '173927', '173928', '173929', '173930', '173931', '173964', '173965', '173966', '173967', '173969', '173970', '173971', '173972', '173974', '173994', '173995', '173999', '174000', '174003', '174004', '182163']
nosy_count = 13.0
nosy_names = ['loewis', 'georg.brandl', 'terry.reedy', 'techtonik', 'stutzbach', 'ezio.melotti', 'eric.araujo', 'chris.jerdonek', 'docs@python', 'codefisher', 'tshepang', 'python-dev', 'yselivanov']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'needs patch'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue8040'
versions = ['Python 3.3', 'Python 3.4']

[stutzbach]

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)

[loewis]

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

[terryjreedy]

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.

[ezio-melotti]

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.

[stutzbach]

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.

[stutzbach]

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.

[terryjreedy]

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.

[ezio-melotti]

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

[codefisher]

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

[stutzbach]

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?