Thanks to visit codestin.com
Credit goes to github.com

Skip to content

bpo-25910: Link redirections in docs #1933

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 21 commits into from
Jan 20, 2018

Conversation

CuriousLearner
Copy link
Member

@CuriousLearner CuriousLearner commented Jun 3, 2017

This is a Work in Progress PR to address link fixes in documentation.

I intend to address url redirection issues in this PR.

Please let me know what changes are needed in this. Thanks!

https://bugs.python.org/issue25910

@mention-bot
Copy link

@CuriousLearner, thanks for your PR! By analyzing the history of the files in this pull request, we identified @birkenfeld, @serhiy-storchaka, @ncoghlan and @tiran to be potential reviewers.

@Mariatta Mariatta changed the title Fix issue25910: Link redirections in docs bpo-25910: Link redirections in docs Jun 3, 2017
@Mariatta Mariatta added docs Documentation in the Doc dir needs backport to 3.5 labels Jun 3, 2017
Copy link
Member

@serhiy-storchaka serhiy-storchaka left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have doubts about most of changes. Links shouldn't contain language or version specific parts or expose implementation details of a site if the original link is working.

Replacing "http" with "https" LGTM. Removing "/en/latest/" LGTM.

@@ -52,8 +52,8 @@ currently exists, you can try wrapping the library's data types and functions
with a tool such as `SWIG <http://www.swig.org>`_. `SIP
<https://riverbankcomputing.com/software/sip/intro>`__, `CXX
<http://cxx.sourceforge.net/>`_ `Boost
<http://www.boost.org/libs/python/doc/index.html>`_, or `Weave
<https://scipy.github.io/devdocs/tutorial/weave.html>`_ are also
<http://www.boost.org/doc/libs/1_64_0/libs/python/doc/html/index.html>`_, or
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The redirection is changed regularly after releasing every new version of Boost. This FAQ is not specific to particular Boost version. The general version of the link should be used.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.

Doc/about.rst Outdated
@@ -7,7 +7,7 @@ These documents are generated from `reStructuredText`_ sources by `Sphinx`_, a
document processor specifically written for the Python documentation.

.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://sphinx-doc.org/
.. _Sphinx: http://www.sphinx-doc.org/en/stable/
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This replaces language agnostic link with language specific link. If the resource has versions on other languages (or will have in future) and the redirection is based on user's preferences, this replacement is not valid.

www. is optional.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, indeed you're right about this. I've made the changes

@@ -53,7 +53,7 @@ commercial use, to sell copies of Python in source or binary form (modified or
unmodified), or to sell products that incorporate Python in some form. We would
still like to know about all commercial use of Python, of course.

See `the PSF license page <https://www.python.org/psf/license/>`_ to find further
See `the PSF license page <https://docs.python.org/3/license.html>`_ to find further
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Keep the original link.

Doc/faq/gui.rst Outdated
@@ -90,7 +90,7 @@ Kivy is free and open source software distributed under the MIT license.
FLTK
----

Python bindings for `the FLTK toolkit <http://www.fltk.org>`_, a simple yet
Python bindings for `the FLTK toolkit <http://www.fltk.org/index.php>`_, a simple yet
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/index.php is an implementation detail. It just means that currently the site is implemented in PHP. After rewiting it on Python that link likely will become not valid.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But that is an issue in that website, not in this docs, isn’t it?
If the goal of the PR is to avoid redirects, and the fltk website currently redirects / to /whatever.implementiation.detail, the change here is correct?

Copy link
Member Author

@CuriousLearner CuriousLearner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @serhiy-storchaka !

I've fixed the issues you mentioned.

Doc/about.rst Outdated
@@ -7,7 +7,7 @@ These documents are generated from `reStructuredText`_ sources by `Sphinx`_, a
document processor specifically written for the Python documentation.

.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://sphinx-doc.org/
.. _Sphinx: http://www.sphinx-doc.org/en/stable/
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, indeed you're right about this. I've made the changes

@@ -52,8 +52,8 @@ currently exists, you can try wrapping the library's data types and functions
with a tool such as `SWIG <http://www.swig.org>`_. `SIP
<https://riverbankcomputing.com/software/sip/intro>`__, `CXX
<http://cxx.sourceforge.net/>`_ `Boost
<http://www.boost.org/libs/python/doc/index.html>`_, or `Weave
<https://scipy.github.io/devdocs/tutorial/weave.html>`_ are also
<http://www.boost.org/doc/libs/1_64_0/libs/python/doc/html/index.html>`_, or
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.

@serhiy-storchaka
Copy link
Member

Please fix all similar issues.

@CuriousLearner
Copy link
Member Author

@serhiy-storchaka sure, on it.

@CuriousLearner
Copy link
Member Author

@serhiy-storchaka in the linkchecker/output.txt there were many redirection to /latest urls. Should I remove those changes all together? since I've introduced some of them in this PR.

@@ -35,7 +35,7 @@ Key terms
repository of open source licensed packages made available for use by
other Python users
* the `Python Packaging Authority
<https://www.pypa.io/>`__ are the group of
<https://www.pypa.io/en/latest/>`__ are the group of
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@serhiy-storchaka like here. should I remove these kind of changes?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, remove.

@serhiy-storchaka
Copy link
Member

If the web-server returns the HTTP code in the range 3XX except 301 (Moved Permanently) or 308 (Permanent Redirect), we should keep the original link. For www.pypa.io the code 302 (Found) is returned.

I think it is better to remove all additions of /en/latest/ if the stripped links are working.

@CuriousLearner
Copy link
Member Author

Hi @serhiy-storchaka!

I've tried to resolve all the issues with redirection of links.

However I've a concern:
- All the links pointing to github (that are build automatically) are permanently redirected from https://github.com/python/cpython/tree/master/* to https://github.com/python/cpython/blob/master/*

Should we fix these in this PR?

@serhiy-storchaka
Copy link
Member

Should we fix these in this PR?

Not in this PR. If there are reasons for using */blob/* liinks, this should be made in a tool that automatically generates links.

Copy link
Member

@serhiy-storchaka serhiy-storchaka left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have reviewed a half of the PR. Please remove insignificant changes and changes with HTTP code 302. Make similar changes in the other half.

Doc/about.rst Outdated
@@ -7,7 +7,7 @@ These documents are generated from `reStructuredText`_ sources by `Sphinx`_, a
document processor specifically written for the Python documentation.

.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://sphinx-doc.org/
.. _Sphinx: http://www.sphinx-doc.org
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

HTTP/1.1 302 Found

Keep the original link.

@@ -35,7 +35,7 @@ Key terms
repository of open source licensed packages made available for use by
other Python users
* the `Python Packaging Authority
<https://www.pypa.io/>`__ are the group of
<https://www.pypa.io/en/latest/>`__ are the group of
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, remove.

Doc/bugs.rst Outdated
@@ -68,7 +68,7 @@ taken on the bug.

.. seealso::

`How to Report Bugs Effectively <http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_
`How to Report Bugs Effectively <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay.

@@ -62,7 +62,7 @@ Key terms
locally.

.. _setuptools: https://setuptools.readthedocs.io/en/latest/
.. _wheel: https://wheel.readthedocs.org
.. _wheel: https://wheel.readthedocs.io/
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay.

@@ -111,7 +111,7 @@ by invoking the ``pip`` module at the command line::
The Python Packaging User Guide includes more details on the `currently
recommended tools`_.

.. _currently recommended tools: https://packaging.python.org/en/latest/current/#packaging-tool-recommendations
.. _currently recommended tools: https://packaging.python.org/current/#packaging-tool-recommendations
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@@ -69,7 +69,7 @@ plug-ins to add a custom feature. In addition to the bug checking that
PyChecker performs, Pylint offers some additional features such as checking line
length, whether variable names are well-formed according to your coding
standard, whether declared interfaces are fully implemented, and more.
https://docs.pylint.org/ provides a full list of Pylint's features.
https://pylint.readthedocs.io/ provides a full list of Pylint's features.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

HTTP/1.1 302 FOUND

Keep the original link.

@@ -100,7 +100,7 @@ which don't. One is Thomas Heller's py2exe (Windows only) at

http://www.py2exe.org/

Another tool is Anthony Tuininga's `cx_Freeze <http://cx-freeze.sourceforge.net/>`_.
Another tool is Anthony Tuininga's `cx_Freeze <https://anthony-tuininga.github.io/cx_Freeze/>`_.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay.

@@ -170,8 +170,8 @@ offender.
How do I make an executable from a Python script?
-------------------------------------------------

See http://cx-freeze.sourceforge.net/ for a distutils extension that allows you
to create console and GUI executables from Python code.
See https://anthony-tuininga.github.io/cx_Freeze/ for a distutils extension
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay.

@@ -341,5 +341,5 @@ This is a mistake; the extension should be .TGZ.

Simply rename the downloaded file to have the .TGZ extension, and WinZip will be
able to handle it. (If your copy of WinZip doesn't, get a newer one from
https://www.winzip.com.)
http://www.winzip.com/.)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Insignificant change.

Doc/glossary.rst Outdated
@@ -126,7 +126,7 @@ Glossary

BDFL
Benevolent Dictator For Life, a.k.a. `Guido van Rossum
<https://www.python.org/~guido/>`_, Python's creator.
<https://gvanrossum.github.io/>`_, Python's creator.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay.

@CuriousLearner
Copy link
Member Author

Hi @serhiy-storchaka I've done the changes. Also, for the other half, I've tried to do similar changes. Can you please have a look now?

@CuriousLearner
Copy link
Member Author

@serhiy-storchaka Can you please take a look here once?

@CuriousLearner
Copy link
Member Author

Hey @serhiy-storchaka ,

Just wanted to ping you to know if it would be possible for you to take a look here once.

Thanks :)

@marco-buttu
Copy link
Contributor

@CuriousLearner and @serhiy-storchaka, does this pull request aim to fix only link redirections, as the title says? Because in your first message you wrote: "This is a Work in Progress PR to address link fixes in documentation", and also bpo-25910 is focusing on Fixing links in documentation, so the goal is not clear to me. I am asking because if this PR wants to fix all documentation links, than we have to close #2765 .

@@ -869,7 +869,7 @@ Constants

Whether the OpenSSL library has built-in support for *Next Protocol
Negotiation* as described in the `NPN draft specification
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The link label is now outdated.

@@ -1502,7 +1502,7 @@ to speed up repeated connections from the same clients.
handshake. It should be a list of strings, like ``['http/1.1', 'spdy/2']``,
ordered by preference. The selection of a protocol will happen during the
handshake, and will play out according to the `NPN draft specification
<https://tools.ietf.org/html/draft-agl-tls-nextprotoneg>`_. After a
<https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation >`_. After a
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ditto

@CuriousLearner
Copy link
Member Author

I've just run make linkcheck again to check more issues like this. I will update the PR once that is done. :)

@@ -218,10 +218,10 @@ queen threatens another) and the Knight's Tour (a route that takes a knight to
every square of an $NxN$ chessboard without visiting any square twice).

The idea of generators comes from other programming languages, especially Icon
(https://www.cs.arizona.edu/icon/), where the idea of generators is central. In
(https://www2.cs.arizona.edu/icon/), where the idea of generators is central. In
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please keep the original link. While it's currently a redirection to https://www2.cs.arizona.edu/icon/ we can still find https://www.cs.arizona.edu/icon/ on the site itself, but also on Wikipedia.

@jdufresne
Copy link
Contributor

I found the following *.readthedocs.org links that still exist that should probably be changed to *.readthedocs.io:

./Doc/library/ast.rst:264:    `Green Tree Snakes <https://greentreesnakes.readthedocs.org/>`_, an external documentation resource, has good
./Doc/library/unittest.mock-examples.rst:1254:<https://pyhamcrest.readthedocs.org/>`_ provides similar functionality,
./Doc/whatsnew/2.5.rst:333:   https://pylib.readthedocs.org/

I suggest this based on the fact that:

  • *.readthedocs.org links redirect to *.readthedocs.io (can save a redirect)
  • *.readthedocs.io is preferred by Read the docs for cookie security concerns

For additional details, see:

https://blog.readthedocs.com/securing-subdomains/

Starting today, Read the Docs will start hosting projects from subdomains on the domain readthedocs.io, instead of on readthedocs.org. This change addresses some security concerns around site cookies while hosting user generated data on the same domain as our dashboard.

@jdufresne
Copy link
Contributor

jdufresne commented Jan 6, 2018

I also found the following links that should be updated to use https.

./Doc/library/string.rst:666:`flufl.i18n <http://flufli18n.readthedocs.io/en/latest/>`_ package.
./Doc/library/smtpd.rst:18:    The `aiosmtpd <http://aiosmtpd.readthedocs.io/>`_ package is a recommended
./Doc/using/mac.rst:69::program:`Gvim` (http://macvim-dev.github.io/macvim/) and :program:`Aquamacs`

@CuriousLearner
Copy link
Member Author

Thanks for your inputs @jdufresne . I've fixed those things in 3cd462

@vstinner I'm not sure about this change:

faq/general.rst:56: [redirected permanently] https://www.python.org/psf/license/ to https://docs.python.org/3/license.html

Apart from that, there are several redirection from https://packaging.python.org/installing/ to https://packaging.python.org/tutorials/installing-packages/ Should they be also fixed?

Note: I've left the redirections for Github links; for which I'll file a separate PR.

Copy link
Member

@vstinner vstinner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not good yet. But this time, I added "ok" comment on each correct change. So the next review should be quicker for me.

FYI I copied/pasted each time manually to open them in Firefox, it took me "forever" to check all these links...

@@ -111,7 +111,7 @@ by invoking the ``pip`` module at the command line::
The Python Packaging User Guide includes more details on the `currently
recommended tools`_.

.. _currently recommended tools: https://packaging.python.org/en/latest/current/#packaging-tool-recommendations
.. _currently recommended tools: https://packaging.python.org/guides/tool-recommendations/#packaging-tool-recommendations
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok

@@ -124,11 +124,11 @@ involved in creating a project:
* `Uploading the project to the Python Packaging Index`_

.. _Project structure: \
https://packaging.python.org/en/latest/distributing/
https://packaging.python.org/tutorials/distributing-packages/
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok

.. _Building and packaging the project: \
https://packaging.python.org/en/latest/distributing/#packaging-your-project
https://packaging.python.org/tutorials/distributing-packages/#packaging-your-project
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok

.. _Uploading the project to the Python Packaging Index: \
https://packaging.python.org/en/latest/distributing/#uploading-your-project-to-pypi
https://packaging.python.org/tutorials/distributing-packages/#uploading-your-project-to-pypi
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok

@@ -160,7 +160,7 @@ Python Packaging User Guide for more information and recommendations.
.. seealso::

`Python Packaging User Guide: Binary Extensions
<https://packaging.python.org/en/latest/extensions>`__
<https://packaging.python.org/guides/packaging-binary-extensions/>`__
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok

@@ -330,7 +330,7 @@ statement, only the ``from ... import`` form.
:pep:`328` - Imports: Multi-Line and Absolute/Relative
PEP written by Aahz; implemented by Thomas Wouters.

https://pylib.readthedocs.org/
https://pylib.readthedocs.io/
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok

@@ -172,7 +172,7 @@ this edition of "What's New in Python" links to the bug/patch
item for each change.

Hosting of the Python bug tracker is kindly provided by
`Upfront Systems <http://www.upfrontsystems.co.za/>`__
`Upfront Systems <http://www.upfrontsoftware.co.za>`__
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok

@@ -1545,7 +1545,7 @@ changes, or look through the Subversion logs for all the details.
*ciphers* argument that's a string listing the encryption algorithms
to be allowed; the format of the string is described
`in the OpenSSL documentation
<https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT>`__.
<https://www.openssl.org/docs/manmaster/man1/ciphers.html#CIPHER-LIST-FORMAT>`__.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok

@@ -1643,7 +1643,7 @@ for secure (encrypted, authenticated) internet connections:
* The :func:`ssl.wrap_socket` constructor function now takes a *ciphers*
argument. The *ciphers* string lists the allowed encryption algorithms using
the format described in the `OpenSSL documentation
<https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT>`__.
<https://www.openssl.org/docs/manmaster/man1/ciphers.html#CIPHER-LIST-FORMAT>`__.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok

@@ -1568,7 +1568,7 @@ mark class variables. As introduced in :pep:`526`, a variable annotation
wrapped in ClassVar indicates that a given attribute is intended to be used as
a class variable and should not be set on instances of that class.
(Contributed by Ivan Levkivskyi in `Github #280
<https://github.com/python/typing/issues/280>`_.)
<https://github.com/python/typing/pull/280>`_.)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok

@CuriousLearner
Copy link
Member Author

Hey @vstinner

"FYI I copied/pasted each time manually to open them in Firefox, it took me "forever" to check all these links..."

I really appreciate all the efforts you've put in to review this PR. Thank a lot. I've addressed the reviews, and now I think it would take a lot less time to review.

Also, please see this query: #1933 (comment)

@vstinner
Copy link
Member

@vstinner I'm not sure about this change: faq/general.rst:56: [redirected permanently] https://www.python.org/psf/license/ to https://docs.python.org/3/license.html

In case of doubt, do nothing. I see that you kept https://www.python.org/psf/license/ : good.

@vstinner vstinner dismissed serhiy-storchaka’s stale review January 20, 2018 00:25

The author fixed issues reported by Serhiy

@vstinner vstinner merged commit 338cd83 into python:master Jan 20, 2018
@miss-islington
Copy link
Contributor

Thanks @CuriousLearner for the PR, and @vstinner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.6.
🐍🍒⛏🤖

@miss-islington
Copy link
Contributor

Sorry, @CuriousLearner and @vstinner, I could not cleanly backport this to 3.6 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 338cd83c5dceaed785f5bf613e2122f871908e2a 3.6

@vstinner
Copy link
Member

I don't think that it's worth it to backport this change to Python 3.6 (I missed the "need 3.6 backport" label when I merged this PR).

@vstinner
Copy link
Member

I merged your PR @CuriousLearner, thanks.

@CuriousLearner
Copy link
Member Author

Thanks a lot @vstinner :)

@serhiy-storchaka serhiy-storchaka removed their assignment Dec 6, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir skip news
Projects
None yet
Development

Successfully merging this pull request may close these issues.