Python interpreter discovery (#50163)

* Python interpreter discovery

* No longer blindly default to only `/usr/bin/python`
* `ansible_python_interpreter` defaults to `auto_legacy`, which will discover the platform Python interpreter on some platforms (but still favor `/usr/bin/python` if present for backward compatibility). Use `auto` to always use the discovered interpreter, append `_silent` to either value to suppress warnings.
* includes new doc utility method `get_versioned_doclink` to generate a major.minor versioned doclink against docs.ansible.com (or some other config-overridden URL)

* docs revisions for python interpreter discovery

(cherry picked from commit 5b53c0012ab7212304c28fdd24cb33fd8ff755c2)

* verify output on some distros, cleanup

test/units/executor/module_common/test_modify_module.py

@@ -27,10 +27,11 @@ def fake_old_module_open(mocker):
     else:
         mocker.patch('builtins.open', m)
 
-
-def test_shebang(fake_old_module_open, templar):
-    (data, style, shebang) = modify_module('fake_module', 'fake_path', {}, templar)
-    assert shebang == '#!/usr/bin/python'
+# this test no longer makes sense, since a Python module will always either have interpreter discovery run or
+# an explicit interpreter passed (so we'll never default to the module shebang)
+# def test_shebang(fake_old_module_open, templar):
+#     (data, style, shebang) = modify_module('fake_module', 'fake_path', {}, templar)
+#     assert shebang == '#!/usr/bin/python'
 
 
 def test_shebang_task_vars(fake_old_module_open, templar):

test/units/executor/module_common/test_module_common.py

@@ -24,6 +24,7 @@ import pytest
 import ansible.errors
 
 from ansible.executor import module_common as amc
+from ansible.executor.interpreter_discovery import InterpreterDiscoveryRequiredError
 from ansible.module_utils.six import PY2
 
 
@@ -105,7 +106,10 @@ def templar():
 class TestGetShebang(object):
     """Note: We may want to change the API of this function in the future.  It isn't a great API"""
     def test_no_interpreter_set(self, templar):
-        assert amc._get_shebang(u'/usr/bin/python', {}, templar) == (None, u'/usr/bin/python')
+        # normally this would return /usr/bin/python, but so long as we're defaulting to auto python discovery, we'll get
+        # an InterpreterDiscoveryRequiredError here instead
+        with pytest.raises(InterpreterDiscoveryRequiredError):
+            amc._get_shebang(u'/usr/bin/python', {}, templar)
 
     def test_non_python_interpreter(self, templar):
         assert amc._get_shebang(u'/usr/bin/ruby', {}, templar) == (None, u'/usr/bin/ruby')