From bbac77c31f801c4db8c8c148294f9a8a2dfd9f73 Mon Sep 17 00:00:00 2001
From: Xavier Claessens <xavier.claessens@collabora.com>
Date: Wed, 12 Sep 2018 16:08:38 -0400
Subject: [PATCH] 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               | 14 ++++++++++++++
 .../snippets/deprecated_python3_module.md      | 18 ++++++++++++++++++
 2 files changed, 32 insertions(+)
 create mode 100644 docs/markdown/snippets/deprecated_python3_module.md

diff --git a/docs/markdown/Python-3-module.md b/docs/markdown/Python-3-module.md
index 7dda67218..187a3ecf9 100644
--- a/docs/markdown/Python-3-module.md
+++ b/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.
diff --git a/docs/markdown/snippets/deprecated_python3_module.md b/docs/markdown/snippets/deprecated_python3_module.md
new file mode 100644
index 000000000..2c4683001
--- /dev/null
+++ b/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()
+```
+