[2.7] Doc: Add an optional obsolete header. (GH-13638) #19229

leonardr · 2020-03-30T12:48:18Z

(ported from commits 46ed90d and 00f46db)

Co-authored-by: Julien Palard julien@palard.fr

My apologies for the multiple PRs; it took me a couple tries to get this right.

the-knights-who-say-ni · 2020-03-30T12:48:21Z

Hello, and thanks for your contribution!

I'm a bot set up to make sure that the project can legally accept this contribution by verifying everyone involved has signed the PSF contributor agreement (CLA).

CLA Missing

Our records indicate the following people have not signed the CLA:

@leonardr

For legal reasons we need all the people listed to sign the CLA before we can look at your contribution. Please follow the steps outlined in the CPython devguide to rectify this issue.

If you have recently signed the CLA, please wait at least one business day
before our records are updated.

You can check yourself to see if the CLA has been received.

Thanks again for the contribution, we look forward to reviewing it!

…r than the table of supported branches.

brainwane · 2020-04-14T04:38:07Z

@benjaminp Please review. Thank you.

merwok · 2020-04-16T18:20:36Z

Doc/tools/templates/layout.html

+<div id="outdated-warning" style="padding: .5em; text-align: center; background-color: #FFBABA; color: #6A0E0E;">
+    {% trans %}This document is for an old version of Python that is {% endtrans %}<a href="https://devguide.python.org/devcycle/#end-of-life-branches">{% trans %}no longer supported{% endtrans %}</a>.
+    {% trans %}You should upgrade, and read the {% endtrans %}
+    <a href="/3/{{ pagename }}{{ file_suffix }}">{% trans %} Python documentation for the current stable release{% endtrans %}</a>.


Could you try adding {{ language or 'en' }} like below on line 8/18?

I tried this out and it almost works, but https://docs.python.org/en/3/ isn't a working URL the way https://docs.python.org/ja/3/ and https://docs.python.org/pt-br/3/ are.

I used the ternary operator to get something which is unelegant but works. I tested it three ways:

with no language set: make html 'SPHINXOPTS=-A outdated=1'

with the language set to 'en': make html 'SPHINXOPTS=-A outdated=1 -A language=en'

with the language set to a value other than 'en': make html 'SPHINXOPTS=-A outdated=1 -A language=pt-br'

Let me know what you think.

Sounds great to me, but I’m not the expert on Python docs translations, I’ll tag Julien.

…plicable.

…ugh links.

ned-deily · 2020-04-17T22:10:30Z

Doc/tools/templates/layout.html

+<div id="outdated-warning" style="padding: .5em; text-align: center; background-color: #FFBABA; color: #6A0E0E;">
+    {% trans %}This document is for an old version of Python that is {% endtrans %}<a href="https://devguide.python.org/devcycle/#end-of-life-branches">{% trans %}no longer supported{% endtrans %}</a>.
+    {% trans %}You should upgrade, and read the {% endtrans %}
+    <a href="/{{ language + '/' if language and language != 'en' else '' }}3/{{ pagename }}{{ file_suffix }}">{% trans %} Python documentation for the current stable release{% endtrans %}</a>.


This href needs to be an absolute URL to the website and not just relative because the docs are also produced as a downloadable set of files for a particular release and thus need to work when browsing via files. Try building the docs and then opening the built file directly in a browser (for example. on macOS, if you were in the Doc directory, you could just type 'open build/html/index.html')

ned-deily · 2020-04-17T22:16:18Z

Doc/README.txt

+Deprecation header
+==================
+
+You can define the ``outdated`` variable in ``html_context`` to show a


Since we're merging this change into 2.7 at the time it is being end-of-lifed, the "outdated" variable should be always set when building the 2.7 docs and not depend on being passed in from the "make" command. (We also build the docs in various ways so it would be problematic to modify all the make calls.) I'm not sure where the best place to put the definition is; just so it ends up in the branch.

bedevere-bot · 2020-04-17T22:16:36Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

…e now always outdated.

…n absolute URL on docs.python.org.

… because the banner is displayed by default.

leonardr · 2020-04-17T23:23:05Z

I have made the requested changes; please review again.

The link template in Doc/tools/templates/layout.html is now absolute.
I've reworded Doc/README.txt to convey that the banner is to be expected and it's not necessary to do anything special to get it to show up.
outdated is now set in Doc/conf.py This means it's now possible to build the docs without specifying -A outdated=1. I tested it with these two commands:

make html
make html 'SPHINXOPTS=-A language=pt-br'

(The setting of outdated is also handled by my docsbuild-scripts PR, which can be extended to other releases as support for them ends.)

bedevere-bot · 2020-04-17T23:23:08Z

Thanks for making the requested changes!

@ned-deily: please review the changes made to this pull request.

ned-deily

Thanks for the changes! Those look good to me. Note, I'm not that familiar with how all the internationalization works so it would still be good to have @JulienPalard review this.

leonardr added 2 commits March 30, 2020 08:27

[2.7] Doc: Add an optional obsolete header. (pythonGH-13638)

b47d9bc

Use the more precise wording set in revision 525e408.

f93d321

bedevere-bot added skip issue skip news labels Mar 30, 2020

the-knights-who-say-ni added the CLA not signed label Mar 30, 2020

bedevere-bot added the awaiting review label Mar 30, 2020

leonardr mentioned this pull request Mar 30, 2020

Python 2 sunset preparation: docs.python.org deep links python/steering-council#3

Closed

Added a link to the document that lists the status of Python branches.

5276022

leonardr mentioned this pull request Apr 11, 2020

Add an --outdated flag to the build_docs.py script, which sets the 'outdated' value within HTML templates. python/docsbuild-scripts#86

Closed

Link 'no longer supported' to the table of end-of-life branches rathe…

fa07217

…r than the table of supported branches.

the-knights-who-say-ni added CLA signed and removed CLA not signed labels Apr 11, 2020

merwok reviewed Apr 16, 2020

View reviewed changes

leonardr added 2 commits April 16, 2020 17:01

Add a language code to the URL of the up-to-date documentation, if ap…

50e2dbd

…plicable.

Change README to reflect the fact that language is now preserved thro…

a8d7d7f

…ugh links.

merwok requested a review from JulienPalard April 16, 2020 21:17

ned-deily requested changes Apr 17, 2020

View reviewed changes

bedevere-bot added awaiting changes and removed awaiting review labels Apr 17, 2020

leonardr added 3 commits April 17, 2020 19:02

Always set 'outdated' in the HTML context, because Python 2.7 docs ar…

25567b7

…e now always outdated.

When linking to the latest version of a documentation file, link to a…

0f373bc

…n absolute URL on docs.python.org.

Reword the portion of the README referring to the deprecation banner,…

3628e76

… because the banner is displayed by default.

bedevere-bot added awaiting change review and removed awaiting changes labels Apr 17, 2020

bedevere-bot requested a review from ned-deily April 17, 2020 23:23

ned-deily approved these changes Apr 17, 2020

View reviewed changes

bedevere-bot added awaiting merge and removed awaiting change review labels Apr 17, 2020

benjaminp merged commit 0fc82e9 into python:2.7 Apr 18, 2020

bedevere-bot removed the awaiting merge label Apr 18, 2020

leonardr deleted the backport-46ed90d-2.7 branch April 18, 2020 23:01

ncoghlan requested a review from benjaminp April 19, 2020 07:00

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

[2.7] Doc: Add an optional obsolete header. (GH-13638) #19229

[2.7] Doc: Add an optional obsolete header. (GH-13638) #19229

Uh oh!

leonardr commented Mar 30, 2020

Uh oh!

the-knights-who-say-ni commented Mar 30, 2020

Uh oh!

brainwane commented Apr 14, 2020

Uh oh!

merwok Apr 16, 2020

Uh oh!

leonardr Apr 16, 2020

Uh oh!

merwok Apr 16, 2020

Uh oh!

ned-deily Apr 17, 2020

Uh oh!

ned-deily Apr 17, 2020

Uh oh!

bedevere-bot commented Apr 17, 2020

Uh oh!

leonardr commented Apr 17, 2020

Uh oh!

bedevere-bot commented Apr 17, 2020

Uh oh!

ned-deily left a comment

Uh oh!

Uh oh!

Uh oh!

[2.7] Doc: Add an optional obsolete header. (GH-13638) #19229

[2.7] Doc: Add an optional obsolete header. (GH-13638) #19229

Uh oh!

Conversation

leonardr commented Mar 30, 2020

Uh oh!

the-knights-who-say-ni commented Mar 30, 2020

CLA Missing

Uh oh!

brainwane commented Apr 14, 2020

Uh oh!

merwok Apr 16, 2020

Choose a reason for hiding this comment

Uh oh!

leonardr Apr 16, 2020

Choose a reason for hiding this comment

Uh oh!

merwok Apr 16, 2020

Choose a reason for hiding this comment

Uh oh!

ned-deily Apr 17, 2020

Choose a reason for hiding this comment

Uh oh!

ned-deily Apr 17, 2020

Choose a reason for hiding this comment

Uh oh!

bedevere-bot commented Apr 17, 2020

Uh oh!

leonardr commented Apr 17, 2020

Uh oh!

bedevere-bot commented Apr 17, 2020

Uh oh!

ned-deily left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!