Doc: Deprecate python3 module [skip ci]

The new 'python' module is a superset of its features, keeping both is
confusing.

Closes #4168.

docs/markdown/Python-3-module.md

@@ -3,6 +3,8 @@
 This module provides support for dealing with Python 3. It has the
 following methods.
 
+This module is deprecated and replaced by the [python](Python-module.html) module.
+
 ## find_python
 
 This is a cross platform way of finding the Python 3 executable, which
@@ -11,6 +13,9 @@ may have a different name on different operating systems. Returns an
 
 *Added 0.38.0*
 
+Deprecated, replaced by [`find_installation`](Python-module.html#find_installation)
+function from `python` module.
+
 ## extension_module
 
 Creates a `shared_module` target that is named according to the naming
@@ -24,15 +29,24 @@ need to add `dependencies : dependency('python3')`, see
 
 *Added 0.38.0*
 
+Deprecated, replaced by [`extension_module`](Python-module.html#extension_module)
+method from `python` module.
+
 ## language_version
 
 Returns a string with the Python language version such as `3.5`.
 
 *Added 0.40.0*
 
+Deprecated, replaced by [`language_version`](Python-module.html#language_version)
+method from `python` module.
+
 ## sysconfig_path
 
 Returns the Python sysconfig path without prefix, such as
 `lib/python3.6/site-packages`.
 
 *Added 0.40.0*
+
+Deprecated, replaced by [`get_path`](Python-module.html#get_path)
+method from `python` module.

docs/markdown/snippets/deprecated_python3_module.md

@@ -0,0 +1,18 @@
+## python3 module is deprecated
+
+A generic module `python` has been added in Meson `0.46.0` and has a superset of
+the features implemented by the previous `python3` module.
+
+In most cases, it is a simple matter of renaming:
+```meson
+py3mod = import('python3')
+python = py3mod.find_python()
+```
+
+becomes
+
+```meson
+pymod = import('python')
+python = pymod.find_installation()
+```
+