From c3d99dd2e414b9b953bb0815ac14af61b7d1dd7b Mon Sep 17 00:00:00 2001
From: Roland Dobai <dobai.roland@gmail.com>
Date: Fri, 7 Sep 2018 09:14:05 +0200
Subject: [PATCH] Encourage to install python packages without administrative
 rights

Using 'sudo pip install' can cause a lot of problems because usually
there are a couple of Python interpreters installed. This fix encourages
developers to use `pip install --user` instead which is safer.
---
 docs/en/contribute/documenting-code.rst             | 2 +-
 docs/en/get-started-cmake/macos-setup-scratch.rst   | 2 +-
 docs/en/get-started-cmake/macos-setup.rst           | 2 +-
 docs/en/get-started-cmake/windows-setup-scratch.rst | 2 +-
 docs/en/get-started/index.rst                       | 6 +-----
 docs/requirements.txt                               | 2 +-
 docs/zh_CN/get-started/index.rst                    | 8 +-------
 tools/check_python_dependencies.py                  | 2 +-
 tools/tiny-test-fw/docs/index.rst                   | 2 +-
 9 files changed, 9 insertions(+), 19 deletions(-)

diff --git a/docs/en/contribute/documenting-code.rst b/docs/en/contribute/documenting-code.rst
index fd7d93866c..bcbe66eafa 100644
--- a/docs/en/contribute/documenting-code.rst
+++ b/docs/en/contribute/documenting-code.rst
@@ -298,7 +298,7 @@ All remaining applications are `Python <https://www.python.org/>`_ packages and
 ::
 
 	cd ~/esp/esp-idf/docs
-	pip install -r requirements.txt
+	pip install --user -r requirements.txt
 
 .. note::
 
diff --git a/docs/en/get-started-cmake/macos-setup-scratch.rst b/docs/en/get-started-cmake/macos-setup-scratch.rst
index ae6e8c43ed..d75a1a8bb1 100644
--- a/docs/en/get-started-cmake/macos-setup-scratch.rst
+++ b/docs/en/get-started-cmake/macos-setup-scratch.rst
@@ -23,7 +23,7 @@ Install Prerequisites
 
 - install pyserial::
 
-    sudo pip install pyserial
+    pip install --user pyserial
 
 - install CMake & Ninja build:
 
diff --git a/docs/en/get-started-cmake/macos-setup.rst b/docs/en/get-started-cmake/macos-setup.rst
index 21a780c526..6a4241f4f3 100644
--- a/docs/en/get-started-cmake/macos-setup.rst
+++ b/docs/en/get-started-cmake/macos-setup.rst
@@ -15,7 +15,7 @@ ESP-IDF will use the version of Python installed by default on Mac OS.
 
 - install pyserial::
 
-    sudo pip install pyserial
+    pip install --user pyserial
 
 - install CMake & Ninja build:
 
diff --git a/docs/en/get-started-cmake/windows-setup-scratch.rst b/docs/en/get-started-cmake/windows-setup-scratch.rst
index d8381ae686..58c6af9e22 100644
--- a/docs/en/get-started-cmake/windows-setup-scratch.rst
+++ b/docs/en/get-started-cmake/windows-setup-scratch.rst
@@ -42,7 +42,7 @@ The "Customise" step of the Python installer gives a list of options. The last o
 
 Once Python is installed, open a Windows Command Prompt from the Start menu and run the following command::
 
-  pip install pyserial
+  pip install --user pyserial
 
 MConf for IDF
 ^^^^^^^^^^^^^
diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst
index c558dbf38a..1d14de4df0 100644
--- a/docs/en/get-started/index.rst
+++ b/docs/en/get-started/index.rst
@@ -143,10 +143,6 @@ Install the Required Python Packages
 
 Python packages required by ESP-IDF are located in the ``$IDF_PATH/requirements.txt`` file. You can install them by running::
 
-    sudo python -m pip install -r $IDF_PATH/requirements.txt
-
-or you can use the following command for installing them into the user install directory on systems where you don't have administrator rights::
-
     python -m pip install --user -r $IDF_PATH/requirements.txt
 
 .. note::
@@ -155,7 +151,7 @@ or you can use the following command for installing them into the user install d
     interpreter can be checked by running command ``python --version`` and depending on the result, you might want to
     use ``python2``, ``python2.7`` or similar instead of ``python``, e.g.::
 
-        sudo python2.7 -m pip install -r $IDF_PATH/requirements.txt
+        python2.7 -m pip install --user -r $IDF_PATH/requirements.txt
 
 .. _get-started-start-project:
 
diff --git a/docs/requirements.txt b/docs/requirements.txt
index dfd6f5c08a..6a4de8f3f6 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,5 +1,5 @@
 # This is a list of python packages used to generate documentation. This file is used with pip:
-# pip install -r requirements.txt
+# pip install --user -r requirements.txt
 #
 sphinx==1.6.5
 sphinx-rtd-theme
diff --git a/docs/zh_CN/get-started/index.rst b/docs/zh_CN/get-started/index.rst
index 11ff33a8f6..7ec10482c4 100644
--- a/docs/zh_CN/get-started/index.rst
+++ b/docs/zh_CN/get-started/index.rst
@@ -142,12 +142,6 @@ ESP32 是一套 Wi-Fi (2.4 GHz) 和蓝牙 (4.2) 双模解决方案，集成了
 
 ESP-IDF 所依赖的 Python 软件包位于 ``$IDF_PATH/requirements.txt`` 文件中，您可以通过运行以下命令来安装它们：
 
-.. code:: bash
-
-    sudo python -m pip install -r $IDF_PATH/requirements.txt
-
-如果您没有系统的管理员权限，那么可以使用如下命令来将软件包安装到用户目录中：
-
 .. code:: bash
 
     python -m pip install --user -r $IDF_PATH/requirements.txt
@@ -156,7 +150,7 @@ ESP-IDF 所依赖的 Python 软件包位于 ``$IDF_PATH/requirements.txt`` 文
 
     请调用 ESP-IDF 使用的相同版本的 Python 解释器，解释器的版本号可以通过运行命令 ``python --version`` 来获得，根据结果，您可能要使用 ``python2``, ``python2.7`` 或者类似的名字而不是 ``python``,例如::
 
-        sudo python2.7 -m pip install -r $IDF_PATH/requirements.txt
+        python2.7 -m pip install --user -r $IDF_PATH/requirements.txt
 
 .. _get-started-start-project:
 
diff --git a/tools/check_python_dependencies.py b/tools/check_python_dependencies.py
index 30eaffc021..4f03d0650d 100755
--- a/tools/check_python_dependencies.py
+++ b/tools/check_python_dependencies.py
@@ -47,7 +47,7 @@ if __name__ == "__main__":
         print('The following Python requirements are not satisfied:')
         for requirement in not_satisfied:
             print(requirement)
-        print('Please run "{} -m pip install -r {}" for resolving the issue.'.format(sys.executable, args.requirements))
+        print('Please run "{} -m pip install --user -r {}" for resolving the issue.'.format(sys.executable, args.requirements))
         sys.exit(1)
 
     print('Python requirements from {} are satisfied.'.format(args.requirements))
diff --git a/tools/tiny-test-fw/docs/index.rst b/tools/tiny-test-fw/docs/index.rst
index 76bd236d07..af5115a92c 100644
--- a/tools/tiny-test-fw/docs/index.rst
+++ b/tools/tiny-test-fw/docs/index.rst
@@ -190,7 +190,7 @@ The following 3rd party lib is required:
     * netifaces
     * matplotlib (if use Utility.LineChart)
 
-These libraries can be installed by running ``pip install -r requirements.txt`` in tiny-test-fw directory.
+These libraries can be installed by running ``pip install --user -r requirements.txt`` in tiny-test-fw directory.
 
 To build document, we need to install ``Sphinx``, ``plantweb`` and ``sphinx-rtd-theme`` (you may replace this with your own theme). ``plantweb`` requires internet access during building document.
 
-- 
2.40.0