Python 2 sunset preparation: docs.python.org deep links

[ncoghlan]

The current handling of deep links on docs.python.org is covered by PEP 430:

• unqualified deep links resolve to the Python 2.7 documentation
• the canonical URL for up to date Python 3 documentation includes a /3/ segment in the path

That approach made sense when I wrote PEP 430, but that's almost 7 years ago now, and there's the potential to ask the PSF for assistance in the somewhat tedious task of implementing a more sophisticated solution for adoption as part of the Python 2 sunsetting process (and also easing a possible future transition to a python 4.0 release if we ever decide to make one of those rather than continuing with double-digit minor versions in the 3.x series).

I'm not planning to write that PEP myself, but some potential ideas that it could cover:

• switching the canonical URL for the English Python documentation from "docs.python.org/3/" to "docs.python.org/en/" (in alignment with PEP 545)
• setting the canonical URL even on old maintenance branches that are otherwise no longer receiving documentation updates (either by making one final commit to them, or by amending the HTML files directly on the documentation hosting server)
• setting the canonical URL meta tag even in the Python 2.7 documentation to refer to the relevant "docs.python.org/en/" URL (but do the work to handle module renames and other moves correctly)
• adding a banner to end of life versions that clearly indicates that the specified version is no longer receiving security updates, and potentially also linking to the latest version (see https://docs.djangoproject.com/en/1.10/ref/django-admin/ for an example of such a banner, albeit without a direct link to more recent documentation)

[gvanrossum]

I don't think this discussion necessarily needs to be carried out in the SC's domain. Perhaps move these ideas to Discourse or python-ideas?

[ncoghlan]

The part that I think is in the SC's domain is the fact that unlike most things, this kind of has a deadline associated with it (i.e. the planned sunset date for Python 2.7).

But yeah, one possible resolution at our level is "No need to complete the work by any specific date, so just file it as a regular docs issue and see if anyone takes it up".

[gvanrossum]

I don't see how the SC can make this happen faster, unless we volunteer to do it ourselves -- but I just don't see the priority. The sky isn't falling even if we don't do this.

[warsaw]

I concur. I don't think there's much for the SC to do, unless there's some objection to making the Python 3 documentation "the default". But that's an easy pronouncement. :)

[brettcannon]

Let's start with the discussion out in the open and then we can act as tiebreaker if necessary.

[brainwane]

Followup to this and the SC's July update for other folks reading along: The PSF has hired Changeset Consulting (my firm) to do a bunch of documentation updates on python.org, to improve communication about the sunsetting. More details on my blog.

[ned-deily]

If you are planning to make changes to the cpython docs, you should ensure that the release managers (@benjaminp et al) and our release documentation expert (@JulienPalard) are reviewing any PRs and discussion about them to ease their adoption and minimize long-term maintenance issues. In particular, I'm wondering if there's a reason why @leonardr in the message above appears to create a PR to their own clone; if it's going to go into cpython, the PR needs to be made against the python/cpython repo.

[brainwane]

Thanks for the guidance. Leonard deliberately created that PR against his own fork so I could review it first, by the way.

[JulienPalard]

Thanks @ned-deily for the heads up, I'm not following issues of the SC repo.

@brainwane: I implemented the deprecation header a year ago (python/cpython@46ed90d), documented it in the Doc/README.rst file and we're already using it in production for some old releases like https://docs.python.org/3.4/.

[leonardr]

Julien, thank you for the guidance and for the work you've already done. I've put up python/cpython#19229, which backports your work to 2.7 and incorporates the wording change made later (changing "last" to "current").

I have two remaining concerns. First, the deprecation notice is general; for 2.7 the thinking was we'd have a message that linked to the sunsetting document. Should we change the string (creating more translation work) or leave it consistent across versions?

The second concern is probably just a point of information: I don't understand how the html_context is populated. On python.org I see this banner for 3.4, but not any other version, and I don't see any branch that defines html_context in its Doc/conf.py file. So I'm assuming html_context is populated during the documentation build process. I looked at the docsbuild-scripts projects and didn't see it mentioned there. I'm sure this is just my ignorance speaking, but want to make sure there's nothing missing from my PR.

[JulienPalard]

I have two remaining concerns. First, the deprecation notice is general; for 2.7 the thinking was we'd have a message that linked to the sunsetting document. Should we change the string (creating more translation work) or leave it consistent across versions?

I'd prefer consistency between versions, and a simple message, over personalisation, but I'm not against linking to a cross-version-"sunsetting info" page from every versions, maybe simply https://devguide.python.org/#status-of-python-branches, or a more specific one. If we go for https://devguide.python.org/#status-of-python-branches, a link from it to the 2.7-sunsetting page can be added for discoverability.

The second concern is probably just a point of information: I don't understand how the html_context is populated. On python.org I see this banner for 3.4, but not any other version, and I don't see any branch that defines html_context in its Doc/conf.py file. So I'm assuming html_context is populated during the documentation build process.

Right, I admit the README goes a bit fast about it, sorry.

I looked at the docsbuild-scripts projects and didn't see it mentioned there.

The 3.4 doc is no longer automatically built, so I think the 3.4 documentation was just manually built with a make autobuild-stable SPHINXOPTS='-D html_context.outdated=1', one last time, to add the banner.

For 2.7 it can be added from docsbuild_scripts, I have it in my todo list but low priority util 2.7.18, I did not wanted to rush a big red banner on 2.7. So you can either PR it or leave it in my todo list :)

[vstinner]

I like the idea of a single banner for all Python versions which are no longer supported. I also like the idea of pointing to a single web page which gives the status of all branches.

https://devguide.python.org/#status-of-python-branches can easily be modified to add a link to https://www.python.org/doc/sunset-python-2/ for Python 2.